On-Chip Debugging

FPGA hardware can fail in ways that are hard to see from outside. On-chip debugging lets you observe internal signals after the bitstream is running.

Learning Objectives

You will learn to:

choose between simulation and hardware debug;
expose useful debug signals;
use integrated logic analyzers conceptually;
create triggers and capture windows;
avoid changing the bug while debugging it.

Debugging Order

flowchart TD A["Failing behavior"] --> B["Can simulation reproduce it?"] B -->|yes| C["Fix in simulation first"] B -->|no| D["Add hardware observability"] D --> E["ILA / SignalTap / debug UART / LEDs"] E --> F["Capture trigger"] F --> G["Compare with expected timing"]

Simulation is still the cheapest debugger. Hardware debug is for board-specific behavior, real timing, I/O, integration, or bugs missing from the testbench.

Debug Tools

Tool	Good for	Limitation
LEDs	heartbeat, simple state indication	very low bandwidth
UART/debug stream	counters, status logs	consumes pins/logic and can perturb timing
Integrated logic analyzer	internal waveform capture	limited sample depth
External logic analyzer	pins and protocols	cannot see internal nets unless exported
Assertions in simulation	proving expected behavior	not a hardware probe by default

Design for Debug

Add debug-friendly structure:

state encodings with readable names;
error counters;
sticky status flags;
valid/ready signals at interfaces;
heartbeat counters per clock domain;
optional debug muxes or capture registers.

Trigger Strategy

Do not capture randomly. Define what event matters:

FSM enters ERROR;
FIFO full occurs;
packet checksum fails;
timeout counter expires;
valid asserted while ready is low for too long.

Capture signals around that trigger.

Worked Example: FIFO Underflow

Symptom: output data occasionally repeats.

Debug signals:

rd_en;
empty;
rd_data;
read pointer;
write pointer synchronized into read domain;
consumer ready/valid.

Likely trigger:

rd_en && empty

If this ever occurs, the consumer is reading without data available or the empty flag logic is wrong.

Common Mistakes

Debugging hardware before writing a real testbench.
Capturing too many signals with too little depth.
Adding debug logic that changes timing and hides the bug.
Forgetting to remove or guard debug-only logic.
Ignoring clock domains in captured signals.

Summary

On-chip debug is powerful when used deliberately. Start with simulation, add targeted observability, trigger on meaningful events, and interpret captured waveforms against the design intent. Debug features should be part of the engineering plan, not desperation wiring.

Next: Introduction to Verilog HDL.

Mind Map

mindmap root((On Chip Debug)) Core concept Internal logic analyzer Trigger captures events Probes cost resources Applications Applications Rare bugs Board bring up Checks Design checks Probe clock Trigger depth Common mistakes Changing timing with probes Common mistakes No simulation baseline