Troubleshooting

Build failures

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

  1. 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.

  2. Did you correctly follow the build instructions?
    Please check the build instructions carefully as you may have missed a step.

  3. 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).

PetaLinux issues

Ports not working

Check the following if you are unable to get ports working in PetaLinux.

  1. Check the interface-to-port assignment for your design
    The assignment of interfaces to ports (Ethernet FMC port 0, 1, 2 and 3) is specific to the design that you are using. PetaLinux 2025.2 uses systemd predictable interface names, so the PS GEM ports appear as end0–end3 on Zynq UltraScale+ and as enx<mac> on Zynq-7000. The interface-to-port assignment is documented here.

  2. 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 end0=192.168.1.10, end1=192.168.2.10, end2=192.168.3.10, end3=192.168.4.10.

  3. GEM unable to generate target frequency: 125000000 Hz
    This message is benign — the macb driver complains that it cannot exactly produce the 125 MHz GMII transmit clock from the available PS clock dividers, then falls back to a slightly different value that the GMII-to-RGMII shim accepts. The link still trains at 1 Gbps/Full. It does not need to be acted on.

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)

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.