RealDigital RFSoC 4x2 Tutorial

Introduction

Backup from Zynq

All Jupyter notebooks are kepts on the ARM chip, so when you edit them, they reside there. You will have to periodically backup by hand (until we find a better way). To do this:

• Open up a windows Powershell window on the computer you are using (assuming it's a windows machine but you can translate to a Mac easily). Then cd to the area you want to back up to.
• On the 4x2 board that most of these tutorials are written for, we have a directory where we keep all of the ADMX files (bit, hwh, and notebooks) called ADMX. It is in this directory:

  		/home/xilinx/jupyter_notebooks/ADMX
  	

• The board we are using is connected to the windows laptop via the USB-3 connector, so it comes up at 192.168.3.1. On the windows machine , do this:

  		scp -r xilinx@192.168.3.1:/home/xilinx/jupyter_notebooks/ADMX .
  	

  It will prompt you for the password, which is Traumerei.admx0 and after you enter that, the entire directory will be backed up.

  I keep a copy on my dropbox account in case anyone needs it.

There are a handful of good tutorials out there, and I will try to collect them here.

In the top image you will see an SD card input at the top left of the 1st 3 push buttons. The RealDigital 4x2 board ships with an SD card that is supposed to be loaded, but it doesn't work for some odd reason. So you will have to build your own from scratch. Here's a tutorial on how to do it:

The RealDigital 4x2 board has data converters integrated with the FPGA and the ARM processors. The converters do everything needed to produce 2 DACs that with sampling times of 9.85 GSps, and 4 ADCs with sampling times of 5 GSps. These devices are used in the context of software radio, which means the specialize at mixing signals with carrier waves, as in the following figure:

NCO stands for numerically controlled oscillator, which means the carrier wave, and the converter will generate both the in-phase (I, a cosine) with the quadrature (Q, sin) carrier wave. For the DAC, you input a waveform, with separate I and Q parts, and the converter will multiply the carrier I with the waveform I, same with Q, and mix the two together. For the ADC, it will mix the carrier (from the NCO) I and Q with the incoming waveform to recover the modulation I and Q parts.

The NCO is worth understanding: how does it produce a sine and cosine with arbitrary frequencies without tuning an analog oscillator? The way it works is complicated, but you can get a good idea from the following: imaging a lookup table (LUT) that has $2^{40}$ addresses, and at each address is a value such that if you plot that value for all $2^{40}$ addresses, you'd see a pretty high resolultion cosine wave. Then you have a 40-bit register (called a "phase accumulator") that points to one of the values in the table, and that value is taken out and shoved into the phase accumulator DAC. If you had a clock that would run at 9.85 GHz, and every tick of that clock you increment the phase accumulator by 1/2 * $2^{40}-1$, then the analog output from the DAC would change at 9.85 GHz, from $+$ to $-$ and generate a wave at 1/2*98.5 GHz = 4.925 GHz. If on the other hand you increment the phase accumulator by 1, then it would take $2^{40}$ ticks to go through an entire cycle, which gives you an output frequency of $4.925 GHz/2^{40} = 4.48 mHz$ (milliHerz), and that would look pretty continuous since the phase would only be changing by 1 part in $2^{40}$ on each clock cycle.

Now let's say that you wanted the output of the DAC to change slower such that the outgoing analog carrier wave was at, for example, 100MHz. You can do this easily by changing the value you increment the phase accumulator. So to get a 100MHz tone, you increment the phase accumulator by a value of $(100\times 10^6)/(4.925 \times 10^9) \times 2^{40}$ which comes to $2.233\times 10^{10}$, which in hex is $532AE24F0$. Voila, you can generate any frequency you want to within 4.48 mHz resolution.

This is basically how it works, except that in actuality it employs a great deal of tricks. For instance, the cosine wave is very symmetric over the 4 quarters of a cycle, and there are ways to reduce the number of values in the LUT by a great deal (imagine the graduate students with theses that worked on this problem!).

On the board there is a 30pin 2-row connector at the bottom right with the labels "PMODB" on the left and "PMODA" on the right.

The following table gives the mapping for what pins on the connector are connected to what FPGA IO pin number:

The 30-pin connector is constructed so that it looks like 2 "standard" 12-pin PMOD connectors (that's what PmodA and PmodB label) separated by 2 rows of 3 pins in between. That standard, which is probably not universal but seems to be generally accepted, has 2 rows of signals, with 4 signals in the first right-most pin followed by ground and power (usually 3.3V). The pins are usually labeled with the top right ("Pin 1") as pin pin 1, followed by 2, 3, 4, followed by ground on pin 5, and power on pin 6. The bottom row starts with pin 7, with pin 11 as ground and 12 as power.

Using the 30-pin connector

It's probably not so important to make this 30-pin connector look like 2 PMOD connectors with 6 extra signals, since what we will probably be using this connector for is to bring out signals for debugging. So let's make a labeling scheme that matches a 22-bit vector (call it PMOD[21:0]) that gets translated onto this connector such that PMOD[0] is the upper right, and PMOD[11] is the lower right, with numbers increasing to the left and skipping the 4 grounds and 4 power pins. So the connector looks like this:

The contstraints file that you will have to edit should have the following (the last 3 constraints are just generally good things to enable):

set_property PACKAGE_PIN AF16 [ get_ports "PMOD[0]" ]
set_property PACKAGE_PIN AG17 [ get_ports "PMOD[1]" ]
set_property PACKAGE_PIN AJ16 [ get_ports "PMOD[2]" ]
set_property PACKAGE_PIN AK17 [ get_ports "PMOD[3]" ]
set_property PACKAGE_PIN AW16 [ get_ports "PMOD[4]" ]
set_property PACKAGE_PIN AW15 [ get_ports "PMOD[5]" ]
set_property PACKAGE_PIN AW14 [ get_ports "PMOD[6]" ]
set_property PACKAGE_PIN AW13 [ get_ports "PMOD[7]" ]
set_property PACKAGE_PIN AR13 [ get_ports "PMOD[8]" ]
set_property PACKAGE_PIN AU13 [ get_ports "PMOD[9]" ]
set_property PACKAGE_PIN AV13 [ get_ports "PMOD[10]" ]
set_property PACKAGE_PIN AF15 [ get_ports "PMOD[11]" ]
set_property PACKAGE_PIN AF17 [ get_ports "PMOD[12]" ]
set_property PACKAGE_PIN AH17 [ get_ports "PMOD[13]" ]
set_property PACKAGE_PIN AK16 [ get_ports "PMOD[14]" ]
set_property PACKAGE_PIN AR16 [ get_ports "PMOD[15]" ]
set_property PACKAGE_PIN AV16 [ get_ports "PMOD[16]" ]
set_property PACKAGE_PIN AT16 [ get_ports "PMOD[17]" ]
set_property PACKAGE_PIN AU15 [ get_ports "PMOD[18]" ]
set_property PACKAGE_PIN AP14 [ get_ports "PMOD[19]" ]
set_property PACKAGE_PIN AT15 [ get_ports "PMOD[20]" ]
set_property PACKAGE_PIN AU14 [ get_ports "PMOD[21]" ]
set_property IOSTANDARD LVCMOS18 [ get_ports "PMOD[*]" ]

# configure unused IO pins to have internal pull-up resistors
set_property BITSTREAM.CONFIG.UNUSEDPIN PULLUP [current_design]
# enable the over-temperature shutdown feathers
set_property BITSTREAM.CONFIG.OVERTEMPSHUTDOWN ENABLE [current_design]
# compress the bitstream to make it smaller
set_property BITSTREAM.GENERAL.COMPRESS TRUE [current_design]

There's an IP called "Processor System Reset" that is quite useful, and you will see a lot of these in the project. This IP is used to generate reset signals for the various components in a project, and ensures that that resets are all synchronized correctly during startup and when resets occur. It is also very useful for simulation, as most simulation tools won't tell you how a wire or reg changes state without knowing its initial value, which is determined via the reset.

When we want to send a waveform from the ARM chip to the RF converter, we use DMA (explained elsewhere). The DMA engine sends data into the FPGA, which sends it into a FIFO at a high speed. The output of the FIFO will be a 32 bit word, with the lower 16 bits being the input to the I port on the RF converter and the upper 16 bits being the input to the Q port.

To make a new FIFO, right click on any empty space on the design, and select "Add IP...". In the "Search" window type "FIFO generator" and select "FIFO Generator" and hit return. That brings up a new "FIFO Generator" block. Double click. It should look like this:

Here's how you configure it in each of the tabs:

• Basic
  • Interface Type set to AXI Stream
  • Clocking Options set Clcock Type AXI to Indepdnednet Clock
  • At the bottom set "Synchronization Stages across Cross Clock Domain Logic" to 4
• AXI Stream Ports. Set TDATA NUM BYTES to 4 and leave the rest alone
• Config. Set FIFO Depth set to 4096 and that's it
• Status Flags. Nothing to change

Now let's discuss the inputs and outputs. But first, remember that we want this FIFO to be written into by the DMA engine, and read out by the RF Converter. So we want the FIFO to have separate read and write clocks.

• Inputs
• Outputs

  The outputs are all in the context of the AXI bus, which means that there's internal logic you don't have to write to do all of the bus business. Click on the + sign next to "M_AXIS" to expand the list of output ports, which are:

  • m_axis_tdata: This is the data being transferred out of the FIFO. Since you specified 4 bytes in the "AXI Stream Ports" when the fifo was configured, that means 32 bits and this will go into the RF Converter. So the lower 16 are I, upper 16 are Q
  • m_axis_ready: Handshake signal from the RF converter (or whatever the fifo is feeding) indicating that it is ready to receive data, used for flow control in the AXI stream. The fifo will only send data when this signal is asserted.
  • m_axis_tuser: User-defined info along with the data, allows for metadata or control info to be sent with the data stream. This is not used in this project.
  • m_axis_tvalid: A signal from the fifo that the data on m_axis_tdata is valid. Part of the handshake between the fifo and the RF converter.

The RealDigital 4x2 is a complex board with lots of parts that Vivado needs to know about. All of these can be loaded into Vivado so that you can select the entire board in the "Default Parts" panel when you build the project. To do this you do the following:

There are 2 basic ways to save the project in Vivado: you can archive the project into a zip file, or you can create a tcl script that can be used to regenerate the project (explained below).

Archiving is good for preserving the important project files into a zip file, and storing it. The files that get archived are the output of the Vivado build process (synthesis, implementation, and bitstream generation). You make the zip archive by going through the File/Project/Archive menu. There used to be a way in the program ISE, before Vivado, to "clean" unnecessary files but Vivado doesn't seem to have such a command. There might be a way to do it but it's probably overly complicated. Anyway by archiving you can copy the project to another computer, unzip, and then use Vivado on that computer.

There are 2 issues with archving: the zip file can be large; and it's difficult to use the zip file on any version of Vivado other than the version that made the project that was zipped. The alternative is to use tcl, the scripting language that Vivado uses.

Go into the tcl command line (click on "Tcl Console" tab at the bottom panel of Vivado), and issue the following command:

	write_bd_tcl -make_local -no_ip_version name.tcl

will produce a file with filename name.tcl that contains a script that can be used to rebuild the project from scratch by any version of Vivado (within reason, has to support all the IPs etc).

The 4x2 ARM chip that is running all the PYNQ software is the 64 bit chip, running Ubuntu Linux. If you move the power switch on the board from ON to OFF to power it down, you could catch it in a state of doing something that will result in the SD card becoming read-only on the next powerup. So best to open up a terminal window in the Jupyter notebook (click on the "New Launcher") button, which is a big blue rectangle with a "+" sign) and that brings up a new Launcher. Click on the "Terminal" icon, that will log you into the ARM chip. Type

	shutdown now

and wait a few seconds, then you can safely power off the board.