MicroZed Chronicles: A Spartan-7 Debug Laboratory
FPGA Horizons London- October 6th and 7th 2026 - get Tickets here.
The $99 Artix UltraScale+ Explorer Board - learn more here
Over the years of writing this blog, most of the designs we have created have one thing in common: they work - well, after a while.
Of course, getting them working often involves debugging on the hardware, just as many real-world projects do. By the time the blog is published, however, the issues have been found and fixed. It is good that they work, as this allows readers to see and, hopefully, understand the concepts I am trying to communicate.
However, if you are struggling to bring up your own design, seeing how someone has done something previously can be a useful reference point. It does not necessarily help you diagnose the issues that might be plaguing your design.
Before we put anything on silicon, we should be creating test benches which verify the behaviour of the RTL we have created.
This is why many FPGA developers report that they spend the majority of their time on verification and bring-up, especially when debugging hardware on which the design does not behave as the test benches indicated it would (there are, of course, several reasons for this).
Debugging is a skill like any other FPGA development skill. There are a few simple concepts which can help us debug our designs more effectively.
Break the problem into smaller parts.
Simplify the problem by reducing the possible variables and variations.
Create a list of possible causes of the issue.
Instrument the design and verify the results against the possible causes.
Crucially, if you are making changes, change only one thing at a time.
The challenge is that practising debugging normally requires a broken design, and we do not tend to keep those around.
So, in this blog I have created a design which is deliberately broken in several interesting and realistic ways, so we can practise using the Vivado debugging tools against known issues.
This design is a Spartan-7 debug laboratory which targets both the Digilent Arty S7-50 and the AMD SP701 development boards. The design contains a healthy baseline along with six selectable faults.
The active fault is selected at run time using a simple Python control panel which communicates with the FPGA over the USB UART.
The design contains several integrated logic analysers which allow us to isolate and understand the fault characteristics.
The Architecture
The design is built using IP Integrator; whenever possible, I have used AMD IP:
The Clocking Wizard generates the 50 MHz and 12.5 MHz clocks.
The Processor System Reset block manages the startup and clock-lock resets.
The USB UART interface is provided by AXI UARTLite.
This design contains no processor. Instead, a small VHDL AXI-Lite sequencer services the UARTLite registers, with a VHDL command parser implementing the packet protocol and experiment registers used by the GUI.
The main stream datapath uses an AXI4-Stream Data FIFO, sixteen entries deep with 32-bit data and TLAST, while a VHDL module provides the traffic generation, the faults themselves and the application-level checks.
On the debug side, a System ILA with three slots and protocol checkers monitors both sides of the AMD FIFO and the AXI exercise, while two native ILAs capture internal state and the second clock domain. A binary counter, slice and concat provide the heartbeat LED, which, along with the running, sticky-error and MMCM-lock indicators, gives us a quick visual health check.
The UART control registers are on an AXI path which is completely independent of the deliberately faulty AXI exercise. This means that when we trigger the AXI deadlock fault, the control panel can still stop and restart the demonstration. If you have ever hung an AXI interconnect, you will know how valuable an independent control path can be for recovery. It is a lesson worth carrying into your own architectures.
The Experiments
The six faults are chosen to represent bug classes we see time and again on real programmes.
Fault one is a data counter which ignores AXI-Stream backpressure, pressing on regardless when TREADY is low.
Fault two is a TLAST counter which counts clock cycles rather than transfers, a classic misunderstanding of the stream protocol.
Fault three moves onto the AXI write channel, where the AXI-Lite target assumes the address and data are always accepted simultaneously, an assumption which the specification does not guarantee.
Fault four corrupts the last word of a selected packet, but only after an earlier stall, giving us a rare, condition-dependent data corruption to chase.
Fault five is a short pulse lost crossing into the slower clock domain.
Fault six makes the FIFO occupancy counter decrement on a simultaneous push and pop when near full.
Each fault produces a known error bitmap in the diagnostic registers when run with the preset settings, so we always know what the signature of success looks like. The stream, AXI write and CDC laboratories all run together, with the selection enabling one fault path, while healthy mode selects the corrected behaviour everywhere.
Fault six is particularly interesting. The AMD FIFO continues to preserve the stream data perfectly; it is the surrounding VHDL occupancy accounting which is wrong. This gives an occupancy mismatch without a data mismatch and lets us practise one of the hardest judgement calls in debugging: distinguishing a suspected IP failure from a bug in our own RTL wrapped around it.
Using the Laboratory
Building the design is scripted, running Vivado in batch mode with a Tcl build script for either board.
Once the bitstream is programmed and the probes file is associated in Hardware Manager, the workflow is straightforward. Connect the GUI to the FPGA COM port, select an experiment, use Clear and Stop, arm the desired ILA in Vivado, and then click Apply and Restart. The settings are latched together at the restart, and each restart also resets the System ILA protocol checkers, giving a clean capture every time. There is even a snapshot export which saves the diagnostic counters and applied settings as JSON.
From there, the System ILA protocol checkers, advanced trigger capabilities and cross-domain captures let us work through each fault just as we would on a real project: forming a hypothesis, setting a trigger, capturing the evidence and confirming the root cause.
In our next blog we will look at the trigger recipes and capture strategies which expose each of these errors. The project is available on my GitHub, so if you want, you can get a head start by taking a look at it.
FPGA Conference
FPGA Horizons London- October 6th and 7th 2026 - get Tickets here.
FPGA Journal
Read about cutting edge FPGA developments, in the FPGA Horizons Journal or contribute an article.
Workshops and Webinars:
If you enjoyed the blog why not take a look at the free webinars, workshops and training courses we have created over the years. Highlights include:
Upcoming Webinars Timing, RTL Creation, FPGA Math and Mixed Signal
Professional PYNQ Learn how to use PYNQ in your developments
Introduction to Vivado learn how to use AMD Vivado
Ultra96, MiniZed & ZU1 three day course looking at HW, SW and PetaLinux
Arty Z7-20 Class looking at HW, SW and PetaLinux
Mastering MicroBlaze learn how to create MicroBlaze solutions
HLS Hero Workshop learn how to create High Level Synthesis based solutions
Perfecting Petalinux learn how to create and work with PetaLinux OS
Boards
Get an Adiuvo development board:
Adiuvo Embedded System Development board - Embedded System Development Board
Adiuvo Embedded System Tile - Low Risk way to add a FPGA to your design.
SpaceWire CODEC - SpaceWire CODEC, digital download, AXIS Interfaces
SpaceWire RMAP Initiator - SpaceWire RMAP Initiator, digital download, AXIS & AXI4 Interfaces
SpaceWire RMAP Target - SpaceWire Target, digital download, AXI4 and AXIS Interfaces
Embedded System Book
Do you want to know more about designing embedded systems from scratch? Check out our book on creating embedded systems. This book will walk you through all the stages of requirements, architecture, component selection, schematics, layout, and FPGA / software design. We designed and manufactured the board at the heart of the book! The schematics and layout are available in Altium here. Learn more about the board (see previous blogs on Bring up, DDR validation, USB, Sensors) and view the schematics here.
All words in this blog were written by a human.
