Merge pull request #48 from mitchburnett/rfsoc

rfsoc tutorial designs
casper-astro · Aug 18, 2021 · 23a8997 · 23a8997
2 parents d504900 + 429e4c1
commit 23a8997
Show file tree

Hide file tree

Showing 107 changed files with 9,650 additions and 0 deletions.
diff --git a/docs/_static/img/rfsoc/readme/PG269/RFDC-SP-Blk-Diagram.png b/docs/_static/img/rfsoc/readme/PG269/RFDC-SP-Blk-Diagram.png
diff --git a/docs/_static/img/rfsoc/readme/PG269/RFSoC-Block-Diagram.png b/docs/_static/img/rfsoc/readme/PG269/RFSoC-Block-Diagram.png
diff --git a/docs/_static/img/rfsoc/readme/casper-rfsoc-yb-platform-summary.png b/docs/_static/img/rfsoc/readme/casper-rfsoc-yb-platform-summary.png
diff --git a/docs/_static/img/rfsoc/readme/clk-rfsoc2x2.png b/docs/_static/img/rfsoc/readme/clk-rfsoc2x2.png
diff --git a/docs/_static/img/rfsoc/readme/clk-zcu111.png b/docs/_static/img/rfsoc/readme/clk-zcu111.png
diff --git a/docs/_static/img/rfsoc/readme/clk-zcu216.png b/docs/_static/img/rfsoc/readme/clk-zcu216.png
diff --git a/docs/_static/img/rfsoc/readme/clk-zrf16.png b/docs/_static/img/rfsoc/readme/clk-zrf16.png
diff --git a/docs/_static/img/rfsoc/readme/qt-dt-arch12.png b/docs/_static/img/rfsoc/readme/qt-dt-arch12.png
diff --git a/docs/_static/img/rfsoc/readme/rfsoc2x2.jpeg b/docs/_static/img/rfsoc/readme/rfsoc2x2.jpeg
diff --git a/docs/_static/img/rfsoc/readme/rfsoc_spec_table.png b/docs/_static/img/rfsoc/readme/rfsoc_spec_table.png
diff --git a/docs/_static/img/rfsoc/readme/zcu111.jpeg b/docs/_static/img/rfsoc/readme/zcu111.jpeg
diff --git a/docs/_static/img/rfsoc/readme/zcu216.jpeg b/docs/_static/img/rfsoc/readme/zcu216.jpeg
diff --git a/docs/_static/img/rfsoc/readme/zrf16-oscin-mod.jpg b/docs/_static/img/rfsoc/readme/zrf16-oscin-mod.jpg
diff --git a/docs/_static/img/rfsoc/readme/zrf1629dr.jpeg b/docs/_static/img/rfsoc/readme/zrf1629dr.jpeg
diff --git a/docs/_static/img/rfsoc/tut_plat/adder_block.PNG b/docs/_static/img/rfsoc/tut_plat/adder_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/adder_design.PNG b/docs/_static/img/rfsoc/tut_plat/adder_design.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/adder_param1.PNG b/docs/_static/img/rfsoc/tut_plat/adder_param1.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/adder_param2.PNG b/docs/_static/img/rfsoc/tut_plat/adder_param2.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/adder_scope.PNG b/docs/_static/img/rfsoc/tut_plat/adder_scope.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/constant_block.PNG b/docs/_static/img/rfsoc/tut_plat/constant_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/counter_block.PNG b/docs/_static/img/rfsoc/tut_plat/counter_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/counter_control_param.PNG b/docs/_static/img/rfsoc/tut_plat/counter_control_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/counter_design.PNG b/docs/_static/img/rfsoc/tut_plat/counter_design.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/counter_param.PNG b/docs/_static/img/rfsoc/tut_plat/counter_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/counter_scope.PNG b/docs/_static/img/rfsoc/tut_plat/counter_scope.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/counter_value_param.PNG b/docs/_static/img/rfsoc/tut_plat/counter_value_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/gpio_block.PNG b/docs/_static/img/rfsoc/tut_plat/gpio_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/gpio_param.PNG b/docs/_static/img/rfsoc/tut_plat/gpio_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/led_counter_param.PNG b/docs/_static/img/rfsoc/tut_plat/led_counter_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/led_design.PNG b/docs/_static/img/rfsoc/tut_plat/led_design.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/led_gpio_param.PNG b/docs/_static/img/rfsoc/tut_plat/led_gpio_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/led_slice_param.PNG b/docs/_static/img/rfsoc/tut_plat/led_slice_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/platform_block.PNG b/docs/_static/img/rfsoc/tut_plat/platform_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/platform_block_param.PNG b/docs/_static/img/rfsoc/tut_plat/platform_block_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/register_block.PNG b/docs/_static/img/rfsoc/tut_plat/register_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/scope_block.PNG b/docs/_static/img/rfsoc/tut_plat/scope_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/simulate_button.PNG b/docs/_static/img/rfsoc/tut_plat/simulate_button.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/slice_block.PNG b/docs/_static/img/rfsoc/tut_plat/slice_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/slice_enable_param.PNG b/docs/_static/img/rfsoc/tut_plat/slice_enable_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/slice_reset_param.PNG b/docs/_static/img/rfsoc/tut_plat/slice_reset_param.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/system_gen_block.PNG b/docs/_static/img/rfsoc/tut_plat/system_gen_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/term_block.PNG b/docs/_static/img/rfsoc/tut_plat/term_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_plat/whole_design.PNG b/docs/_static/img/rfsoc/tut_plat/whole_design.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/constant_block.PNG b/docs/_static/img/rfsoc/tut_rfdc/constant_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/constant_config.PNG b/docs/_static/img/rfsoc/tut_rfdc/constant_config.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/edge_block.PNG b/docs/_static/img/rfsoc/tut_rfdc/edge_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/edge_config.PNG b/docs/_static/img/rfsoc/tut_rfdc/edge_config.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/rfdc-dt-final.png b/docs/_static/img/rfsoc/tut_rfdc/rfdc-dt-final.png
diff --git a/docs/_static/img/rfsoc/tut_rfdc/rfdc-dt-general-config.png b/docs/_static/img/rfsoc/tut_rfdc/rfdc-dt-general-config.png
diff --git a/docs/_static/img/rfsoc/tut_rfdc/rfdc-dt-tile-config.png b/docs/_static/img/rfsoc/tut_rfdc/rfdc-dt-tile-config.png
diff --git a/docs/_static/img/rfsoc/tut_rfdc/rfdc-qt-final.png b/docs/_static/img/rfsoc/tut_rfdc/rfdc-qt-final.png
diff --git a/docs/_static/img/rfsoc/tut_rfdc/rfdc-qt-general-config.png b/docs/_static/img/rfsoc/tut_rfdc/rfdc-qt-general-config.png
diff --git a/docs/_static/img/rfsoc/tut_rfdc/rfdc-qt-tile-config.png b/docs/_static/img/rfsoc/tut_rfdc/rfdc-qt-tile-config.png
diff --git a/docs/_static/img/rfsoc/tut_rfdc/rfdc_block.PNG b/docs/_static/img/rfsoc/tut_rfdc/rfdc_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/snapshot_block.PNG b/docs/_static/img/rfsoc/tut_rfdc/snapshot_block.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/snapshot_config1.PNG b/docs/_static/img/rfsoc/tut_rfdc/snapshot_config1.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/snapshot_config2.PNG b/docs/_static/img/rfsoc/tut_rfdc/snapshot_config2.PNG
diff --git a/docs/_static/img/rfsoc/tut_rfdc/snapshot_config3.PNG b/docs/_static/img/rfsoc/tut_rfdc/snapshot_config3.PNG
diff --git a/docs/tutorials/rfsoc/platforms/rfsoc2x2.md b/docs/tutorials/rfsoc/platforms/rfsoc2x2.md
@@ -0,0 +1,33 @@
+# RFSoC2x2
+
+vendor [link][pynq-rfsoc2x2]
+
+![](../../../_static/img/rfsoc/readme/rfsoc2x2.jpeg)
+
+# RF Clocking
+The following figure shows a high-level block diagram for the clocking network:
+
+![](../../../_static/img/rfsoc/readme/clk-rfsoc2x2.png)
+
+The PLLs used on this board are the:
+  * LMK04832
+  * LMX2594
+
+The `RESET/GPO` pin of the LMK04832 is connected to the FPGA. The power-on
+default for the `RESET/GPO` pin is as an input with a pulldown resistor. This
+requires that hardware designs include a GPIO to remove reset from the LMK for
+programming.
+
+This can be done in the a CASPER design by using a software register and GPIO
+yellow block.  Configure the software register to be `From Processor` with an
+initial value of `0`, a bitwidth of `1` and a bitfield data type of `2`.
+Configure the GPIO yellow block with I/O group set to `custom`, I/O direction
+`out`, Data Type `Boolean`, and Data bitwidth of `1`.
+
+# ADC Inputs
+This board only exposes two ADC inputs; one input on tile 1 and the other on
+tile 3. Callout `ADC 2` (`J5`) is connected to tile 0 corresponding to ports
+`m0X_axis_tdata` on the `rfdc`. Callout `ADC 1` (`J4`) is connected to tile 2
+corresponding to ports `m2X_axis_tdata` on the `rfdc`.
+
+[pynq-rfsoc2x2]: https://www.rfsoc-pynq.io
diff --git a/docs/tutorials/rfsoc/platforms/zcu111.md b/docs/tutorials/rfsoc/platforms/zcu111.md
@@ -0,0 +1,17 @@
+# ZCU111
+
+vendor [link][zcu111]
+
+![](../../../_static/img/rfsoc/readme/zcu111.jpeg)
+
+# RF Clocking
+The following figure shows a high-level block diagram for the clocking network:
+
+![](../../../_static/img/rfsoc/readme/clk-zcu111.png)
+
+The PLLs used on this board are the:
+  * LMK04208
+  * LMX2594
+
+[zcu111]: https://www.xilinx.com/products/boards-and-kits/zcu111.html
+
diff --git a/docs/tutorials/rfsoc/platforms/zcu208.md b/docs/tutorials/rfsoc/platforms/zcu208.md
@@ -0,0 +1,16 @@
+# ZCU208
+
+vendor [link][zcu208]
+
+# RF Clocking
+
+## Notes
+As the ZCU208 is very similar to the ZCU216 much of the work to casperize this
+platform was done at the same time. However, nothing has been tested on the
+platform as there was no immediate access to this specifc board. There would be
+a little bit of work to test a few things out, but by and large should be
+complete.
+
+[zcu208]: https://www.xilinx.com/products/boards-and-kits/zcu208.html
+
+
diff --git a/docs/tutorials/rfsoc/platforms/zcu216.md b/docs/tutorials/rfsoc/platforms/zcu216.md
@@ -0,0 +1,33 @@
+# ZCU216
+
+vendor [link][zcu216]
+
+![](../../../_static/img/rfsoc/readme/zcu216.jpeg)
+
+# RF Clocking
+The following figure shows a high-level block diagram for the clocking network:
+
+![](../../../_static/img/rfsoc/readme/clk-zcu216.png)
+
+The CLK104 board is a seperate module board providing the RF Clocks to the RFSoC
+ADC/DAC tiles. The PLLs on this board are the: 
+  * LMK04828b
+  * LMX2594
+
+Only two of the ADC/DAC tiles recieve a clock. The other two are
+not connected. One of the connections to the ADC is from the LMK chip and the
+other tile recieves its clock from the LMX chip.
+
+In this topology this board relies on the Gen 3 clock forwarding capabilites of
+the RFSoC to distribute the sample clock to all ADC tiles ([PG269 Ch.4,
+Clocking][pg269]). The `rfdc` yellow block checks the source of ADC tile clock
+using the RFSoC platform `.yaml` file and uses that information to forward the
+source clock to the other tiles. The platform configuration file for the ZCU216
+is set to receive its sample clock from the LMK (source tile 2), to update the
+platform to use the LMX as the source instead set `adc_clk_src` to `1` for all
+four tiles.
+
+[zcu216]: https://www.xilinx.com/products/boards-and-kits/zcu216.html
+[pg269]: https://www.xilinx.com/support/documentation/ip_documentation/usp_rf_data_converter/v2_4/pg269-rf-data-converter.pdf
+
+
diff --git a/docs/tutorials/rfsoc/platforms/zrf16.md b/docs/tutorials/rfsoc/platforms/zrf16.md
@@ -0,0 +1,56 @@
+# HTG ZRF16
+
+vendor [link][htg-zrf16]
+
+![](../../../_static/img/rfsoc/readme/zrf1629dr.jpeg)
+
+# RF Clocking
+The following figure shows a high-level block diagram for the clocking network:
+
+![](../../../_static/img/rfsoc/readme/clk-zrf16.png)
+
+The PLLs on this board are:
+  * LMX04832
+  * LMX2594
+
+The distributed hexdump `.txt` file used in the tutorial examples uses the LMK
+in single loop mode. This is because of difficulty to lock PLL2 in [dual-loop
+mode](#lmk-dual-loop-mode). This requires that a 1.8 Vpp 10 MHz reference clock
+from 0.5V and 2.3V be applied to `J19` in these example.
+
+For the 3rd generation `49dr` board supporting clock forwarding the platform
+configuration file is by default setup to expect a clock from the connected LMX
+chips. This can be changed to use tile clock forwarding by changing the platform
+configuration file `adc_clk_src` parameter to the index of the desired source
+tile.
+
+# Notes
+
+### Toolflow Compatability 
+The distributed images and toolflow support for both generation revisions of
+this board have been tested on hardware. However, in the process of casperizing
+those boards there were a few board level issues and discrepencies from the
+vendor. Should differeing hardware be present on your platform this could
+require a few patches to support your board.
+
+### LMK Dual Loop Mode
+The examples for this board here configure the LMK to operate in single loop
+mode.  There were problems getting PLL1 on the LMK04832 to lock when configured
+in dual loop mode. Examining the boards and LMK04832 data sheet indicated that
+the `OSCin` pin is not AC coupled using a `0.1 uF` capacitor. Cutting the trace
+to add this capacitord an inserting an 0401 `0.1 uF` beettween the `OSCin` pin
+and ground did seem to resolve the issue with PLL1 being able to lock when using
+the onboard TCXO.
+
+![](../../../_static/img/rfsoc/readme/zrf16-oscin-mod.jpg)
+
+HTG indicates that this has been resolved in later revisions of the board.
+
+### QA
+Testing board functionality showed that the FMC had open connections to some of
+the GTY transceivers connected. HTG did offer to reflow the board but responding
+to have that done there was no response for further instructions.
+
+
+[htg-zrf16]: http://www.hitechglobal.com/Boards/16ADC-DAC_Zynq_RFSOC.htm
+[htg-disclaimers]: ./zrf16#htg-disclaimers
diff --git a/docs/tutorials/rfsoc/readme.md b/docs/tutorials/rfsoc/readme.md
@@ -0,0 +1,110 @@
+# CASPER RFSoC
+
+# Introduction
+This documentation aims to introduce Xilinx Zynq UltraScale+ RFSoC to the CASPER
+community along with the platforms and capabilities currently supported in the
+CASPER tools. The hardware and design flexibility of RFSoC within CASPER will
+continue to proliferate the design philosophy of CASPER of decreasing the
+time-to-science metric and provide a way of bringing the needed capabilities to
+next generation instruments.
+
+Before starting with the tutorials and reviewing the available platforms, the
+following is a brief introduction and overview of the RFSoC architecture and its
+capabilities. The primary source of the information presented here is Xilinx
+documentation and data sheets pertaining to the [Zynq UltraScale+
+RFSoC][xilinx-rfsoc]. Please reference those materials ([PG269][pg269],
+[DS889][ds889], and [DS926][ds926]) for more details as this is a rehashing of
+only some high-level details.
+
+# The RFSoC
+A high-level block diagram of the RFSoC package is shown in the below figure.
+
+![](../../_static/img/rfsoc/readme/PG269/RFSoC-Block-Diagram.png)
+
+The RFSoC integrates programmable logic with the Zynq ARM (A53) processor, high
+speed serial transceivers, and the RF Data Converters (RFDC); a hardened IP core
+implementing all RF functionality. The RFDC groups together multi-gigasample per
+second ADCs (DACs) capable of direct sampling (synthesis) for RF signals up to 6
+GHz (9.85 GHz). Additionally, these cores include digital down (up) converters,
+a mixer capable of a fixed coarse setting or fine frequency tuning by a
+numerically controlled oscillator (NCO), and interpolation and decimation
+filters. A block diagram of the analog signal path for the ADCs is shown in the
+following figure.
+
+![](../../_static/img/rfsoc/readme/PG269/RFDC-SP-Blk-Diagram.png)
+
+The ADCs and DACs are grouped into "tiles" to some extent similar to the idea of
+other columnar tile components of a Xilinx FPGA. In this case however, the ADCs
+or DACs and their supporting components populate the entire tile. There are two
+different tile architectures found in RFSoC devices: quad-tile and dual-tile.
+The number of tiles found in the device and their capabilities varies between
+RFSoC packages and generation. The quad- and dual-tile architectures are
+depicted in the below figure.
+
+![](../../_static/img/rfsoc/readme/qt-dt-arch12.png)
+
+As the RFDC is the focus of the RFSoC, in order to bring the functionality to
+CASPER an RFDC yellow block is needed to access and configure the IP. This
+yellow block instances the underlying Vivado RFDC IP and interfaces to the
+CASPER user in a similar fashion as would be presented to the hardware designer
+in Vivado providing many of the same configuration options. This was done to
+maintain the flexibility of the RFDC and provide as much control as possible
+over its configuration and provide that to the general CASPER user.
+
+The RFDC yellow block is designed to detect the tile architecture (quad/dual)
+and the generation (gen 1/3) of the selected platform as specified by an RFSoC
+platform yellow block. This provides a forward compatibility mechanism as more
+RFSoC platforms are targeted in CASPER and as Xilinx inevitably produces future
+generations of the RFSoC.
+
+# Platforms
+
+![](../../_static/img/rfsoc/readme/casper-rfsoc-yb-platform-summary.png)
+
+The CASPER library contains support and has been tested for the following 6
+RFSoC platforms:
+  * [ZCU216][zcu216]
+  * [ZCU208][zcu208] [\*\*][zcu208-notes]
+  * [ZCU111][zcu111]
+  * [PYNQ RFSoC 2x2][pynq-rfsoc2x2]
+  * [HTG ZRF16-29DR][htg-zrf16] [\*\*][htg-notes]
+  * [HTG ZRF16-49DR][htg-zrf16] [\*\*][htg-notes]
+
+A summary of the board resources taken from the Xlinx RFSoC product selection
+guide is shown in the following table. In the context of astronomy signal
+processing these features are ideal for small form factor and low power
+digitizers streaming raw voltages over 2x100GbE, or suitable as modest sized
+channelizers using the available fabric resources.
+
+![](../../_static/img/rfsoc/readme/rfsoc_spec_table.png)
+
+# Tutorials
+* [Getting Started With RFSoC][getting-started]
+* [RFSoC Platform Yellow Block and Simulink Overview][platform-overview]
+* [Using the RFDC][rfdc]
+* [Example Spectrometer][spectrometer]
+* [100GbE][100g]
+
+## Designs
+* [Tutorial Designs][tutorial-designs]
+
+[xilinx-rfsoc]: https://www.xilinx.com/products/silicon-devices/soc/rfsoc.html#documentation
+[pg269]: https://www.xilinx.com/support/documentation/ip_documentation/usp_rf_data_converter/v2_4/pg269-rf-data-converter.pdf
+[ds889]: https://www.xilinx.com/support/documentation/data_sheets/ds889-zynq-usp-rfsoc-overview.pdf
+[ds926]: https://www.xilinx.com/support/documentation/data_sheets/ds926-zynq-ultrascale-plus-rfsoc.pdf
+
+[zcu216]: ./platforms/zcu216.md#zcu216
+[zcu208]: ./platforms/zcu208.md#zcu208
+[zcu208-notes]: ./platforms/zcu208.md#notes
+[zcu111]: ./platforms/zcu111.md#zcu111
+[pynq-rfsoc2x2]: ./platforms/rfsoc2x2.md#rfsoc2x2
+[htg-zrf16]: ./platforms/zrf16.md#htg-zrf16
+[htg-notes]: ./platforms/zrf16.md#notes
+
+[getting-started]: ./tut_getting_started.md
+[platform-overview]: ./tut_platform.md
+[rfdc]: ./tut_rfdc.md
+[spectrometer]: ./tut_spec.md
+[100g]: ./tut_100g.md
+
+[tutorial-designs]: ../../../rfsoc/
diff --git a/docs/tutorials/rfsoc/tut_100g.md b/docs/tutorials/rfsoc/tut_100g.md
@@ -0,0 +1,5 @@
+# 100GbE
+
+Tutorial in progress...
+
+but simple example designs are ready and found [here](../../../rfsoc/tut_onehundred_gbe)