Vivado Debug

Vivado Programming & Debugging Guide

Based on UG908 (v2025.2). This skill helps choose debug strategies, configure debug cores, and troubleshoot hardware debugging. For complete command syntax, see REFERENCE.md. For TCL execution, use vivado-tcl.

Debug Core Selection

Choose debug cores based on what you need to observe or control:

Decision guide:

Need to capture signal waveforms at full speed?
  YES --> ILA
  NO  --> Need to read/write signals in real-time?
            YES --> VIO (low bandwidth, JTAG rate)
            NO  --> Need to read/write AXI slave registers?
                      YES --> JTAG-to-AXI Master
                      NO  --> Need to coordinate triggers across clock domains?
                                YES --> ILA with Cross-Trigger enabled

Debug Probing Flow Selection

Four approaches to add debug cores, each with different trade-offs:

mark_debug Attribute

Vivado Synthesis Syntax

Verilog:

(* mark_debug = "true" *) wire [7:0] char_fifo_dout;

VHDL:

attribute mark_debug : string;
attribute mark_debug of char_fifo_dout: signal is "true";

Valid values: "TRUE" or "FALSE" (the "SOFT" value is not supported by Vivado synthesis).

config_flows -mark_debug Modes

Control MARK_DEBUG behavior post-synthesis without modifying source files:

Debug Net Icons in Vivado IDE

Hollow green icon  = MARK_DEBUG set, NOT connected to any ILA core
Full green icon    = MARK_DEBUG set, connected to an ILA core
Yellow icon        = No MARK_DEBUG on net, but connected to an ILA core

ILA Configuration Decisions

Data Depth Selection

The C_DATA_DEPTH property controls how many samples the ILA stores. Larger depth consumes more Block RAM:

Rule of thumb: Start with 1024. Increase only when you need more pre/post-trigger context. Each doubling roughly doubles BRAM usage per probe bit.

Key ILA Properties Decision Table

Probe Configuration: Data / Trigger / Both

Each probe port can be configured independently:

Tip: Configuring wide buses as "Trigger Only" when you do not need their waveform significantly reduces BRAM consumption.

Match Units (Comparators)

• Range: 1 to 16 comparators per probe (C_ALL_PROBE_SAME_MU_CNT)
• If C_ADV_TRIGGER=false and C_EN_STRG_QUAL=false: can be 1-16
• If C_ADV_TRIGGER=false and C_EN_STRG_QUAL=true: must be 2-16 (1 reserved for capture control)
• If C_ADV_TRIGGER=true and C_EN_STRG_QUAL=false: can be 1-16
• If C_ADV_TRIGGER=true and C_EN_STRG_QUAL=true: must be 2-16
• Maximum comparators allowed per ILA: 1024
• If Capture Control is enabled, you have 1 to 15 comparators (1 reserved)

Important: In the netlist insertion flow, all probes share the same number of comparators. Use HDL instantiation flow to set different comparator counts per probe.

ILA Cross-Trigger

Architecture

Cross-triggering enables trigger coordination between ILA cores in different clock domains, or between an ILA core and a processor (e.g., Zynq-7000 SoC).

  +------------------+                  +------------------+
  |     ILA 1        |                  |     ILA 2        |
  |                  |                  |                  |
  |   trig_in  <-----+------------------+-- trig_out      |
  |   trig_in_ack ---+------------------+-> trig_out_ack  |
  |                  |                  |                  |
  |   trig_out ------+------------------+-> trig_in       |
  |   trig_out_ack <-+------------------+-- trig_in_ack   |
  +------------------+                  +------------------+

Requirements:

• Enable C_TRIGIN_EN and/or C_TRIGOUT_EN at core generation time
• Use HDL instantiation method to connect TRIG_IN/TRIG_OUT ports to design nets
• The logic driving trig_in must be synchronous to the ILA clock

Cross-Trigger Timing

Behavior: TRIG_OUT remains HIGH until TRIG_OUT_ACK is received. If TRIG_OUT_ACK is tied to LOW, TRIG_OUT remains HIGH until the user re-arms the ILA. Only TRIG_OUT goes LOW if TRIG_OUT_ACK is tied to LOW.

Cross-Trigger Use Cases

• Trigger ILA in slow clock domain from event detected in fast clock domain
• Trigger ILA capture from a software breakpoint on Zynq/Versal processor
• Chain multiple ILA cores to capture a sequence of events across the design

VIO Usage Guide

The VIO (Virtual Input/Output) core monitors and controls signals at JTAG scan rates (not system speed).

Port Types

Typical VIO Use Cases

• Board bring-up: Toggle reset signals, enable/disable subsystems without recompiling
• Status monitoring: Observe PLL lock, FIFO full/empty, error flags in real time
• Stimulus injection: Drive test patterns into data paths at low speed
• ILA trigger coordination: Use VIO output to gate an ILA trigger condition
• Register access substitute: Read/write control registers when JTAG-to-AXI Master is not available

VIO Operating Model

VIO operates on set/commit and refresh/get model:

  Write flow:  set_property OUTPUT_VALUE <val> [get_hw_probes <probe>]
               commit_hw_vio [get_hw_probes {<probe>}]

  Read flow:   refresh_hw_vio [get_hw_vios {hw_vio_1}]
               get_property INPUT_VALUE [get_hw_probes <probe>]

Recommended refresh rate: 500 ms or longer (very small values make Vivado sluggish).

JTAG-to-AXI Master

Capabilities

• Supports all memory-mapped AXI Full and AXI-Lite interfaces
• 32-bit or 64-bit data width
• Create and run read/write burst transactions via TCL
• Queued operation: up to 16 read and 16 write transactions back-to-back

Typical Use Cases

• Read/write peripheral registers without a processor
• Verify AXI slave IP functionality during board bring-up
• Inject data into AXI-connected BRAMs for testing
• Debug AXI interconnect routing issues