Troubleshooting

SSD failures

SSD does not link-up

If you test the SSD using the standalone application of this reference design, and you cannot get link-up, you can try the following:

• If you are using the AXI Bridge for PCI Express Gen3 Subsystem IP (VC709, KCU105), open the project in Vivado, then open the IP configuration for PCIe. There is a tab called “GT Settings” that contains a “Receiver Detect” setting. Change this setting to “Falling Edge”, then save and rebuild the design. Some SSDs require this setting to link up correctly.

• If your SSD has both the B and M keys, then it only has 2x PCIe lanes rather than 4x. In order for a 4-lane PCIe block to operate with a 2-lane SSD, it needs to downshift during the link width negotiation. The Xilinx PCIe blocks support downshifting, however the lanes need to be properly assigned in order for this to work properly. If you are using an SSD with both the B and M keys, and you are not getting link-up, then we suggest you validate the lane assignment in the constraints file with respect to your schematic drawings. If your constraints seem correct, and it is still not working, then we suggest you reverse the lane order assignment in the constraints file (downshifting only works properly if the lane ordering is correct). Alternatively, you can try reconfiguring your PCIe IP for 2 lanes, rather than 4, in which case you would also need to adjust your constraints.

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. 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 build fails with bitbake petalinux-image-minimal failed and sstate fetch errors

If a make petalinux TARGET=<board> run ends with errors like

ERROR: <package>-<ver>-r0 do_..._setscene: Fetcher failure: Unable to find file file://.../sstate:...
[ERROR] Command bitbake petalinux-image-minimal failed

the actual build is not broken. These _setscene errors come from bitbake trying to pull prebuilt artifacts from the public Xilinx sstate-cache mirror, which occasionally returns 404 for individual packages. Bitbake falls back to building those packages locally and succeeds, but still exits non-zero because of the failed fetches — so the Makefile stops before the petalinux-package step that produces BOOT.BIN.

Fix: just re-run the same command. The second attempt finds the missing packages in the local sstate cache (populated by the first run) and completes cleanly, producing BOOT.BIN. The reference design itself is fine; this is a transient issue with the public mirror.