Showing results for 
Show  only  | Search instead for 
Did you mean: 

Debugging PCI Express Link Training Issues with Integrated Debugging Features in the IP

Xilinx Employee
Xilinx Employee
3 0 2,397

The Xilinx PCI Express IP comes with the following integrated debugging features.

  • JTAG Debugger
  • Enable In-System IBERT
  • Descrambler in Gen3 Mode

The 'JTAG Debugger' provides the following information to assist in debugging PCI Express link training issues:

  • A graphical view of LTSSM states
  • A GUI based receiver detect status on all configured lanes
  • PHY RST state machine status

In-system IBERT provides the PCIe link Eye Diagram. The JTAG Debugger and the In-system IBERT features together provide instant information on a probable source of the link training issue. In this blog, we will talk about how to use these features. This blog is based on VCU118 Xilnx Development Board which comes with an UltraScale+ Device.

The Gen3 Mode Descrambler option provides a decoded interface of the scrambled PIPE data. It allows users to view the packets on the PCIe link. Details on this feature and how to decode the packet are available in this blog.

The IP configuration GUI contains an "Add. Debug Options" tab. Select "Enable JTAG Debugger".

After configuring the other IP parameters in the GUI, generate the IP and open the example design.

Make sure that the debug wrapper module is included in the example design 'Design Sources' hierarchy as shown below:


Generate the bitstream and program the device by selecting the correct bit file and the .ltx file.


You might see the following error based on the Vivado tool version you are using.


If you see the above error message, run the following command in the Vivado Tcl Console.

set_param xicom.use_bitstream_version_check false


Reprogram the device.

After successfully programming the target device, an AXI core “hw_axi_1” should appear in the hardware window.


In the project directory, in the location shown below, you will find four .tcl files.

The 'test_rd.tcl' file reads the debug data stored in the BRAM and outputs the *.dat files shown below. The other Tcl files read these *.dat files to draw graphical views of LTSSM, PHY RST state machine, and Receiver Detect respectively.



The draw_ltssm.tcl, draw_reset.tcl and draw_rxdet.tcl scripts are executed using ActiveTcl.

The Vivado tool will error out if you attempt to execute the scripts in its Tcl console.

The figure below shows the LTSSM diagram generated with the “draw_ltssm.tcl” script:


• Green color – transitioned state during the capture window
• Orange color – last state
• Red arrow – last transition state
• Numbers beside the arrow – indicates the number of times the transition happened between the two states

The above diagram is from a working case scenario where the link trains correctly and settles to the 'L0' state. When the link training fails, the 'Detect' bubble might be an Orange color indicating that the IP was not able to detect a receiver. Similarly, you might see a larger number beside one of the arrows, indicating a possible unstable link.

The figure below shows the PHY RST state machine generated using the "draw_reset.tcl" script.


The figure below shows the Receiver Detect status generated using the "draw_rxdet.tcl" script:


As seen above, the green dots indicate successful receiver detect in the corresponding lanes. The GUI also provides information on the negotiated link width.

To capture the PCIe Link Eye Diagram, select the "Enable In System IBERT' option in the "Add. Debug Options" tab of the IP configuration GUI.


Similarly to the 'JTAG Debugger' option, generate the IP and open the example design.

Make sure that you can see the 'System IBERT' module in the 'Design Sources' hierarchy of the example design.


Generate the bitstream and program the bit file along with the .ltx file.

Refer to for the details on the necessary configuration required for IBERT scan. The figure below shows an eye diagram generated with the 'In-System IBERT' feature.


The eye in the above scan is from a working PCIe link. In a failing link, you might see a very small blue region indicating a probable signal integrity issue in the link.

Detailed steps to use the integrated PCIe debug features in Xilinx IP as described in this blog are available in the following answer record:

If you see an issue in the generated graphs and eye diagram using the debug features, see the following answer record that provides information on how to debug PCIe link issues. The results obtained from using the debug features will help in narrowing down the potential source of the issue, making it easier to debug.