Contents

Work Summary, March to June 2023

A summary of the on-and-off work I have done from March this year until now

1 RTL-SDR & PYNQ-Z2

1.1 Current Work

This work connects an RTL-SDR to a PYNQ-Z2 over USB 2.0 so that the two can be used together. The RTL-SDR downconverts the RF signal to a baseband signal. The PYNQ-Z2 receives the baseband signal from the RTL-SDR through its USB 2.0 port and processes it with the FPGA. In the end, a simple FM radio web application can be built in a PYNQ Jupyter Notebook.

PYNQ-Z2 + RTL-SDR

For details, see

1.2 Possible Improvements

  • Tuning with the slider widget in Jupyter Notebook is somewhat laggy. Offloading more of the CPU’s work to the FPGA would reduce the load on the CPU and therefore the lag.

2 AD9361 + PYNQ Kernel

2.1 Current Work

This work is basically to build the PYNQ and AD9361 drivers into the same kernel with Petalinux. MicroPhase in China has done this, but did not use the FPGA for data processing.

On the ZedBoard, the combination of 2019_R1 and PYNQ v2.4 works. Qixing and I summarized the build steps, the problems that may come up, and their solutions at this link.

On the PYNQ-ZU, the BSP exists only for PYNQ v2.7 and later. PYNQ v2.7 needs the 2020 toolchain, and that version ran into some problems (see Section 2.2.1), so this did not succeed.

2.2 Problems Encountered

2.2.1 ADI’s Yocto Layer Is Incompatible with PYNQ

In versions after 2019, the recipes-bsp of meta-adi overwrites the changes introduced by PYNQ’s recipes-bsp.

Below is part of the file meta-adi-xilinx/recipes-bsp/device-tree/device-tree.bbappend:

1
2
3
4
5
do_configure:append() {
    ...
    cp "${KERNEL_DTB_PATH}/${KERNEL_DTB}.dts" "${DT_FILES_PATH}/system-top.dts"
    ...
}

It simply overwrites system-top.dts. A better practice would be to append code to system-top.dts (this is what PYNQ does).

For this reason, I did not manage to build a kernel with ADI master branch + PYNQ v3.0.1. It may be possible to modify recipes-bsp to make it compatible with PYNQ, but this work has been shelved. We also have a good reason to shelve it. See the next section (Section 2.2.2).

In addition, Yocto officially recommends that when several Yocto layers are used, one should check the OpenEmbedded Layer Index and the Yocto Project Compatible Index to see whether the layers are compatible with each other. Unfortunately, neither index includes meta-pynq or meta-adi.

2.2.2 The FPGA MANAGER Problem

The meta-adi-xilinx documentation states explicitly that they have no official support for FPGA MANAGER. If FPGA MANAGER is disabled, the bitstream cannot be reloaded after the board boots. PYNQ then loses its point.

My guess is that ADI treats the FPGA as a peripheral with a fixed function. That is, the device tree and the bitstream are both loaded at boot and are not meant to be changed. This fundamentally contradicts the idea of PYNQ.

Therefore, I do not recommend integrating the AD9361 and PYNQ drivers into one kernel. Instead, the AD9361 device tree and bitstream should be loaded dynamically after the system boots. See the next section (Section 3).

3 User-Space AD9361 Driver

3.1 Existing Work

To get around the difficulty described in the previous section, the AD9361 driver can run in user space and does not have to be integrated into the kernel. However, to talk to the SPI interface of the AD9361, a spidev node has to be added to the Linux device tree, so that SPI can be read and written through the file /dev/spidevx.y.

In /dev/spidevx.y, x is the index of the SPI controller and y is the index of the chip select. With the PS SPI, the device name may be /dev/spidev0.0. With the PL SPI (AXI SPI), the device name may be /dev/spidev1.0.

The device tree is usually loaded by U-Boot at boot and cannot be modified afterwards. Since version 4.14, however, the Linux kernel supports the device tree overlay (DTO for short). A DTO allows a new device tree to be loaded dynamically at run time. The PYNQ library also provides an API for this:

1
class pynq.overlay.Overlay(bitfile_name, dtbo=None, download=True, ignore_version=False, device=None, gen_cache=False)

This API can download the bitstream (bitfile_name) and can also load a new device tree incrementally at run time (dtbo). Below is the device tree code that adds spidev through the AXI SPI:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
/dts-v1/;
/plugin/;
/ {
    fragment@0 {
        target = <&amba>;
        overlay0: __overlay__ {                       
            axi_quad_spi_0: axi_quad_spi@80000000 {
                ...
                status = "okay";
                #address-cells = <1>;
                #size-cells = <0>;
                spidev0: spidev@0 {
                    compatible = "spidev";
                    reg = <0>;
                    spi-max-frequency = <5000000>;
                };
            };                
        };
    };
};

A few points to note:

  • A line /plugin/; has to be added after /dts-v1/; to mark the file as a Device Tree Overlay and not an ordinary Device Tree. ADI’s recipes-bsp decides whether a device tree is an overlay by checking whether the file contains /plugin/;.
  • target specifies which node to modify. Here it is <&amba>, which expands to the phandle of the node labeled amba. For example, if the phandle of the amba node is 70, then <&amba> actually stands for <70>. A phandle uniquely identifies a node and is usually assigned by the compiler (dtc).
  • The compile option -@ is usually needed. It enables symbols, so that device tree nodes can be referenced by label. Otherwise they can only be referenced by the absolute value of the phandle.

The DTO compiled from the file above works with the AXI SPI. This is the earlier work of Qixing and others. However, after the daughter card was changed from the V3 FMC9361_1.0 (datasheet, schematic) to the FMCOMMS2/FMCOMMS3, SPI communication ran into problems. See the next section (Section 3.2).

3.2 Problems Encountered

3.2.1 SPI Communication Problem

  • An AD9361 SPI command is two bytes long, in the following format:

    D15D14D13D12D11D10D9:D0
    W/RNB2NB1NB0XXA[9:0]

    where

    • W/R selects write or read (1 for write, 0 for read),
    • NB2:NB0 is the number of bytes to read or write,
    • A[9:0] is the register address. When sending (writing) data, the data follows the two-byte command. When receiving (reading) data, reading can start right after the command is sent.
  • The register at address 0x037 of the AD9361 stores PRODUCT_ID. For AD9361 Rev 2, PRODUCT_ID should be 0x0A.

  • When the AD9361 is initialized, the driver first performs a hardware reset through GPIO_RESETB (at least 1 us), then reads register 0x037 and checks PRODUCT_ID.

After the V3 FMC9361_1.0 (V3 for short) was replaced with the FMCOMMS2 (S2 for short) and the FMCOMMS3 (S3 for short), and the pin constraints were updated, SPI communication failed.

S2 and S3 can almost be regarded as the same card. Their pin definitions are identical.

There is no public documentation for the V3 card online. This is why we wanted to move to ADI’s official FMCOMMS2/FMCOMMS3 evaluation boards.

Specifically, after the master (the AXI SPI controller) sends 0x037 on MOSI (read the register at address 0x037), the slave (the AD9361) does not send 0x0A (PRODUCT_ID) on MISO. What actually happens is shown below:

Daughter cardSymptomWaveform
V3MISO correctly returns 0x0A/zh-cn/post_20230625_2023-%E5%B9%B4-3-6-%E6%9C%88%E5%B7%A5%E4%BD%9C%E6%80%BB%E7%BB%93/files/spi_write_then_read_v3.png
S2MISO stays low, so 0x00 is read/zh-cn/post_20230625_2023-%E5%B9%B4-3-6-%E6%9C%88%E5%B7%A5%E4%BD%9C%E6%80%BB%E7%BB%93/files/spi_write_then_read_s2.png
S3MISO stays high, so 0xFF is read/zh-cn/post_20230625_2023-%E5%B9%B4-3-6-%E6%9C%88%E5%B7%A5%E4%BD%9C%E6%80%BB%E7%BB%93/files/spi_write_then_read_s3.png

I tried both the Linux SPI driver and a bare-metal program. The symptom was the same.

The factors considered are as follows:

FactorConsideration
Pin constraintsChecked the pin constraints of MOSI, MISO, CS, and CLK of the 4-wire SPI against the schematic several times
ResetConfirmed with the ILA that GPIO_RESETB was pulled low for 1 ms
SPI modeConfirmed that the SPI mode is 0x01 (CPOL=0, CPHA=1)
SPI clockThe clock frequency of the AXI SPI is already set very low in the Block Design (the 10 ns system clock divided by 80). Clock quality can probably be ruled out.
I/O standardConfirmed in the ZU schematic that VADJ is 1.8 V and VCCO is also 1.8 V, as required.
DriverIt is certainly not a software problem, because S2/S3 and V3 use the same driver.
Pins used by SPI and the hardware reset

PYNQ-ZU + FMCOMMS2/3

1
2
3
4
5
6
# pynqzu + fmcomms2/3
set_property -dict {PACKAGE_PIN AG6 IOSTANDARD LVCMOS18 				 }	[get_ports gpio_resetb];  		#Bank 64, FMC_LPC_LA28_P
set_property -dict {PACKAGE_PIN AG1 IOSTANDARD LVCMOS18					 }	[get_ports spi_clk];  			#Bank 64, FMC_LPC_LA26_N
set_property -dict {PACKAGE_PIN AF1 IOSTANDARD LVCMOS18  PULLTYPE PULLUP } 	[get_ports spi_csn];  			#Bank 64, FMC_LPC_LA26_P
set_property -dict {PACKAGE_PIN AF3 IOSTANDARD LVCMOS18                  }	[get_ports spi_miso];  			#Bank 64, FMC_LPC_LA27_N
set_property -dict {PACKAGE_PIN AE3 IOSTANDARD LVCMOS18	                 }	[get_ports spi_mosi];  			#Bank 64, FMC_LPC_LA27_P

PYNQ-ZU + V3 (FMC9361_V1.0)

1
2
3
4
5
6
# pynqzu + v3 (fmc9361_v1.0)
#set_property -dict {PACKAGE_PIN AC9 IOSTANDARD LVCMOS18					 }	[get_ports gpio_resetb]; # LA23_P
#set_property -dict {PACKAGE_PIN AD1 IOSTANDARD LVCMOS18					 }	[get_ports spi_clk];  	# LA18_N
#set_property -dict {PACKAGE_PIN AB2 IOSTANDARD LVCMOS18  PULLTYPE PULLUP    } 	[get_ports spi_csn];  	# LA19_P
#set_property -dict {PACKAGE_PIN AB4 IOSTANDARD LVCMOS18	                 }	[get_ports spi_miso];  	# LA20_P
#set_property -dict {PACKAGE_PIN AD2 IOSTANDARD LVCMOS18	                 }	[get_ports spi_mosi];  	# LA18_P

ZCU104 + FMCOMMS2/3

1
2
3
4
5
6
# zcu104 + fmcomms2/3
set_property -dict {PACKAGE_PIN M13 IOSTANDARD LVCMOS18 				 }	[get_ports gpio_resetb];  		#Bank 64, FMC_LPC_LA28_P
set_property -dict {PACKAGE_PIN B8 IOSTANDARD LVCMOS18					 }	[get_ports spi_clk];  			#Bank 64, FMC_LPC_LA26_N
set_property -dict {PACKAGE_PIN B9 IOSTANDARD LVCMOS18  PULLTYPE PULLUP  } 	[get_ports spi_csn];  			#Bank 64, FMC_LPC_LA26_P
set_property -dict {PACKAGE_PIN A7 IOSTANDARD LVCMOS18					 }	[get_ports spi_miso];  			#Bank 64, FMC_LPC_LA27_N
set_property -dict {PACKAGE_PIN A8 IOSTANDARD LVCMOS18					 }	[get_ports spi_mosi];  			#Bank 64, FMC_LPC_LA27_P
Summary
  • On the ZU + S2/S3 platform, SPI cannot read PRODUCT_ID.

  • The 104/102 + S2/S3 platforms can read PRODUCT_ID, however. This suggests that the problem is probably related to the FMC pins of the ZU itself.

  • The problem did not appear with the V3 daughter card because V3 and S2/S3 use different FMC pins for SPI.

  • Further testing may need an oscilloscope.

  • For now, the ZU board can be put aside in favor of the 104 + S2 platform for the later PYNQ + SDR applications.

3.2.2 *Device Tree Overlay Problem

Loading the Device Tree Overlay (*.dtbo) on the ZCU102/ZCU104 reports no error, but the /dev/spidev1.0 device does not appear.

Apart from the pin constraints and the part number, the Vivado projects for the ZCU102/104 are the same as that for the ZU, so the pl.dtsi generated from the xsa file is no different from the one for the ZU.

My preliminary guess is that the cause is related to the dtc compiler (I seem to have met a similar problem before, and it was caused by the dtc version).

pl.dtsi generated from the xsa
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
/dts-v1/;
/plugin/;
/ {
	fragment@0 {
		target = <&fpga_full>;
		overlay0: __overlay__ {
			...
		};
	};
	fragment@1 {
		target = <&amba>;
		overlay1: __overlay__ {
			...
		};
	};
	fragment@2 {
		target = <&amba>;
		overlay2: __overlay__ {
			#address-cells = <2>;
			#size-cells = <2>;
			...
			axi_quad_spi_0: axi_quad_spi@80000000 {
				bits-per-word = <8>;
				clock-names = "ext_spi_clk", "s_axi_aclk";
				clocks = <&zynqmp_clk 71>, <&zynqmp_clk 71>;
				compatible = "xlnx,axi-quad-spi-3.2", "xlnx,xps-spi-2.00.a";
				fifo-size = <16>;
				interrupt-names = "ip2intc_irpt";
				interrupt-parent = <&gic>;
				interrupts = <0 104 1>;
				num-cs = <0x1>;
				reg = <0x0 0x80000000 0x0 0x10000>;
				xlnx,num-ss-bits = <0x1>;
				xlnx,spi-mode = <0>;
			};
			...
		};
	};
};
system.dtso
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
/dts-v1/;
/plugin/;
/ {
    fragment@0 {
        target = <&amba>;
        overlay0: __overlay__ {                       
            axi_quad_spi_0: axi_quad_spi@80000000 {
                bits-per-word = <8>;
                clock-names = "ext_spi_clk", "s_axi_aclk";
                clocks = <&zynqmp_clk 71>, <&zynqmp_clk 71>;
                compatible = "xlnx,axi-quad-spi-3.2", "xlnx,xps-spi-2.00.a";
                fifo-size = <16>;
                interrupt-names = "ip2intc_irpt";
                interrupt-parent = <&gic>;
                interrupts = <0 104 1>;
                num-cs = <0x1>;
                reg = <0x0 0x80000000 0x0 0x10000>;
                xlnx,num-ss-bits = <0x1>;
                xlnx,spi-mode = <0>;
                status = "okay";
                #address-cells = <1>;
                #size-cells = <0>;
                spidev0: spidev@0 {
                    compatible = "spidev";
                    reg = <0>;
                    spi-max-frequency = <5000000>;
                };
            };                
        };
    };
};

The system.dtbo obtained by compiling the system.dtso file above with dtc -O dtb -o system.dtbo -b 0 -@ system.dtso works on the PYNQ-ZU. On the ZCU104, however, the /dev/spidev1.0 device cannot be found.

Warning

In addition, on both the PYNQ-ZU and the ZCU104, dmesg shows the following warnings:

1
2
3
[  613.794326] OF: overlay: WARNING: memory leak will occur if overlay removed, property: /__symbols__/overlay0
[  613.804196] OF: overlay: WARNING: memory leak will occur if overlay removed, property: /__symbols__/axi_quad_spi_0
[  613.814601] OF: overlay: WARNING: memory leak will occur if overlay removed, property: /__symbols__/spidev0

These warnings can apparently be ignored.

This problem has to be solved if the later PYNQ SDR applications are to be built on the 104 + S2 platform.

4 Summary

ItemResultProblem
Using the PYNQ-Z2 with an RTL-SDRBuilt a small FM radio web app based on Jupyter NotebookPerformance can still be improved
Integrating the AD9361 driver into the PYNQ kernelPYNQ v2.4 + meta-adi 2019_R1 worksIn versions after 2019, meta-adi does not support FPGA_MANAGER
Driving the AD9361 from user spaceWorks on the V3 daughter card. The hardware integrates FFT and FIR IP cores for data processingOn the ZU + S2/S3 platform, SPI cannot read PRODUCT_ID. The 104/102 + S2/S3 platforms can read it, however, which suggests that the problem is probably related to the FMC pins of the ZU itself. The problem did not appear with the V3 daughter card because V3 and S2/S3 use different FMC pins for SPI. Further testing may need an oscilloscope. For now, the ZU board can be put aside in favor of the 104 + S2 platform for the later PYNQ + SDR applications.