Troubleshooting

Build failures

Check the following if the project fails to build or generate a bitstream:

Are you using the correct version of Vivado for this version of the repository?
Check the version specified in the Requirements section of the README.md file. Note that this project is regularly updated and you may have to refer to an earlier commit of this repo if you are using an older version of Vivado.
Did you correctly follow the build instructions?
Please check the build instructions carefully as you may have missed a step.
Did you copy/clone the repo into a short directory structure?
Windows doesn’t cope well with long directory structures, so copy/clone the repo into a short directory structure such as C:\projects\. When working in long directory structures, you can get errors relating to missing files, particularly files that are normally generated by Vivado (FIFOs, etc).

Boot problems

Nothing on the UART after power-on (Yocto image)

If the console stays silent, the BootROM did not find a boot image. With the Yocto image this almost always means that BOOT.BIN was not copied onto the first partition of the SD card after the image was written (step 4 of Prepare the SD card). Also check that the board’s boot-mode switches select the SD card, and that you are looking at the right serial port (on the PYNQ-ZU the console is the second of the two serial ports of the USB-UART).

Boot stops at `Waiting for root device`

The kernel cannot find the root file system on the SD card. When booting through JTAG, the SD card must still be prepared and inserted, because the root file system lives on it. On the UltraZed-EG and UltraZed-EV the SD card is mmcblk1, not mmcblk0; the images of this repository already account for this.

Linux: ports not working

Finding the right interface

The interface names do not follow the Ethernet FMC port numbers, and they differ between the PetaLinux and Yocto images (for example, FMC port 0 is end3 in the Yocto image on Zynq UltraScale+). Identify the ports by their MAC addresses (ip -br link); see Interface names.

Each port must be assigned to a different subnet

If you assign one interface to IP address 192.168.1.10, then you must use a different subnet for the IP address of the other interfaces. Multiple ports that are managed under Linux must be assigned to different subnets, or they will not work. An example address assignment would be 192.168.1.10, 192.168.2.10, 192.168.3.10 and 192.168.4.10 on the four ports.

No link on any FMC port

When none of the FMC ports gets a link, but the PHYs are found, check the FMC power:

VADJ. The Ethernet FMC is powered from the board’s VADJ supply. On the ZCU104, VADJ is switched on by the FSBL only after it has read the FMC card’s EEPROM; this repository patches the FSBL so that it does. If you replace the FSBL (or build BOOT.BIN with a stock one), VADJ stays off and the FMC is unpowered. On boards where VADJ is set by a jumper (ZedBoard) or by the carrier configuration, check the setting.
Card variant. The card’s I/O voltage (1.8 V or 2.5 V variant) must match VADJ; see Choosing the FMC variant. A 2.5 V card on a 1.8 V VADJ slot (or the reverse) is outside the card’s specification, even if some ports seem to work.
Connector. Check that the card is on the FMC connector that your target uses (for example HPC0 for zcu102_hpc0, HPC1 for zcu102_hpc1).

PHY not found, or `Generic PHY` instead of `Marvell 88E1510`

Each FMC port’s PHY is described in the device tree by the port-configuration overlay of the target (ports-0123, ports-012- or ports-0123-axieth; see Advanced). If a port reports no PHY or binds to the Generic PHY driver:

check that the kernel has the Marvell PHY driver (CONFIG_MARVELL_PHY) and, on Zynq UltraScale+, the GMII-to-RGMII driver (CONFIG_XILINX_GMII2RGMII); both are enabled in the bsp.cfg kernel fragments of this repository;
if you changed the block design, check that the port-configuration overlay still matches it: each GEM needs its phy-handle, its mdio node with the PHY at address 0 and, on Zynq UltraScale+, the GMII-to-RGMII node at address 8;
if you added your own board, check the address of its own Ethernet PHY (the ZC706’s board PHY, for example, is at address 7, not 0).

Link is up but no traffic passes, or there are CRC errors

This points to the RGMII timing. On RGMII, the 2 ns clock delay must be added exactly once in each direction:

On the Zynq UltraScale+ ports and the Zynq-7000 port 3, the GMII-to-RGMII core and the PHY together provide the delays; the GEM is configured for GMII towards the core.
The Zynq-7000 AXI Ethernet ports use phy-mode = "rgmii-rxid": the MAC delays the transmit clock and the PHY delays the receive clock. Changing the phy-mode of these ports breaks them.
The board Ethernet ports on MIO (GEM0 on Zynq-7000, GEM3 on zcu102_hpc1) use phy-mode = "rgmii-id", with both delays in the PHY. On the ZCU102 the TI DP83867 PHY also needs its internal delay settings (ti,rx-internal-delay, ti,tx-internal-delay), which the ports-012- overlay provides; without them the link comes up but no packets get through.

Look at the error counters with ip -s link show <interface> and ethtool -S <interface>, and at the PHY’s idle error count with phytool read <interface>/0/10 (see Read the PHY registers).

GEM `unable to generate target frequency: 125000000 Hz`

This message is benign. The GEMs on EMIO take their transmit clock from the PL (the GMII-to-RGMII core), so the macb driver cannot set the clock itself and says so. The link still trains at 1 Gbps/Full. It does not need to be acted on.

Zynq-7000: lower throughput, `rx_resource_errors`

On the Zynq-7000 the throughput of each port is limited by the Cortex-A9 processor (typically 550-770 Mbit/s with iperf3; see Expected results). When a PC sends at full rate, a GEM port can count some rx_resource_errors (the GEM ran out of receive buffers). These are not link errors.

PYNQ-ZU Wi-Fi (Yocto)

wlan0 is down after boot. This is expected until credentials have been set up with wifi-sta-setup (see Wi-Fi on the PYNQ-ZU); the radio is only started by wpa_supplicant once credentials exist.
wifi-sta-setup reports wlan0 not present. The driver did not find the WILC3000; check dmesg | grep -i wilc.
No address after 60 seconds. wifi-sta-setup prints the wpa_cli status. Check the network name, the passphrase and the country code, and that the access point offers 2.4 GHz with WPA2-PSK (or is open). Run wifi-sta-setup again to correct the settings; the journal of the service (journalctl -u wpa_supplicant@wlan0) shows the connection attempts.

Dropped pings/packets

No dropped packets are to be expected with our example designs. If you are experiencing dropped packets of any kind, this can be an indication of one of the following issues:

Timing in the FPGA design is not optimal (check for timing errors in the Vivado design)
Timing of the RGMII interface is not optimal (can be due to the FPGA design or the PHY configuration)
The FMC card variant does not match VADJ (see above)

We ensure that there are no timing errors or issues on all of our designs before making a release, so typically this problem occurs on custom designs where the timing issues have not yet been optimized. Please contact us for support if you are experiencing dropped packets.