shinei-nouzen-arch/fpga-agent/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

Basic Transaction Flow

1. reset_hw_axi [get_hw_axis hw_axi_1]
2. create_hw_axi_txn read_txn [get_hw_axis hw_axi_1] \
     -type READ -address 00000000 -len 4
3. run_hw_axi [get_hw_axi_txns read_txn]
4. report_hw_axi_txn [get_hw_axi_txns read_txn]

Important: If you reprogram the device, all existing jtag_axi transactions are deleted and must be recreated.

Versal Debug Architecture

Versal adaptive SoC uses a different debug infrastructure than 7 series/UltraScale/UltraScale+.

CIPS Requirement

Every Versal design with debug cores requires a Control, Interface, and Processing System (CIPS) IP instance in a block design:

1. Create Block Design in IP Integrator
2. Add CIPS IP to the canvas
3. Generate HDL wrapper
4. Proceed with Netlist Insertion, HDL Instantiation, or IP Integrator debug flow
5. During opt_design, AXI4 Debug Hub is auto-inserted and connected

AXI4 Debug Hub

The AXI4 Debug Hub replaces the BSCAN-based debug hub used in previous architectures. It connects the CIPS AXI4 interface to debug cores via AXI4-Stream.

Supported debug cores on Versal:

• AXI4-Stream ILA (AXIS-ILA) -- includes ILA and System-ILA functionality
• AXI4-Stream VIO (AXIS-VIO)
• PCI Express Link Debugger

Three Connectivity Methods