xilinx/ross-ai-assistant/hw-ila-debug

ILA Debug (EA)

Early Access — this skill may change before general availability.

Interacts with ILA debug cores on live hardware: discover → configure trigger → arm → capture → upload → export → analyze.

See REFERENCE.md for ILA property tables, Tcl command reference, TSM syntax, compare value encoding, and report schema.

Routing: Try Vivado MCP (vivado_execute + Hardware Manager Tcl, below) first if a Vivado MCP session is available — it works across all device families. Fall back to chipscope-mcp (chipscope_ila_core/chipscope_ila_capture) if Vivado MCP is not installed. See Chipscope-mcp Fallback below.

Tools Used

Primary path — Vivado MCP (plus the agent's own file tools):

Fallback path — chipscope-mcp (when Vivado MCP is unavailable): chipscope_session, chipscope_device, chipscope_scan, chipscope_ila_core, chipscope_ila_capture. See Chipscope-mcp Fallback.

No terminal commands, no Python. Everything goes through Vivado MCP or, as fallback, chipscope-mcp.

Session Setup: Vivado Version Must Match hw_server

• vivado_list_sessions → check for an active session.
• Before reusing one, run version -short and compare to the target hw_server's version.
• Mismatch → ERROR: [Labtools 27-3366] Cannot support older hw_server version.
• On mismatch: do not retry or restart automatically. vivado_start does not pick a

matching Vivado version for you — an omitted vivado_path just resolves from PATH, which is often the same mismatched install. Report the exact error, the session's version, and the target hw_server's version to the user, and ask them to point at the correct Vivado install (vivado_path) or the correct hw_server.

• This only applies to an already-running, independently-started hw_server. A

hw_server that Vivado auto-starts itself when connecting to a locally attached board is launched from that same Vivado install, so it cannot be version-mismatched — see "No hw_server" below.

• Only reuse a session once its version matches.

Efficiency Guidelines

• Pass `session_id` to every vivado_execute call — get it from vivado_list_sessions if unknown.
• Verify session version against `hw_server` before reuse, and report a mismatch to the user rather than retrying — see Session Setup above.
• Batch Tcl — discover all ILA cores in one vivado_execute, not separate calls.
• Write reports to file — do not dump full waveform data in chat. Give a short summary only.
• Use `vivado_doc_search` for unfamiliar probe properties, TSM syntax, or compare value encoding.
• Do NOT use display_hw_ila_data — it opens a GUI window. Use write_hw_ila_data + list_hw_samples for data extraction.
• Do NOT use shell commands or Vivado Tcl file I/O. Use agent file tools.
• Do NOT retry failed Tcl with different syntax. Search docs first, then report the error.

Capture & Analysis Workflow

Step 1: Discover ILA Cores & Probes

Run via vivado_execute(session_id=<id>, command=<tcl below>):

puts "=== ILA CORES ==="
foreach ila [get_hw_ilas] {
  puts "ILA:$ila"
  puts "  DATA_DEPTH:[get_property CONTROL.DATA_DEPTH $ila]"
  puts "  MAX_DEPTH:[get_property STATIC.MAX_DATA_DEPTH $ila]"
  puts "  TRIGGER_MODE:[get_property CONTROL.TRIGGER_MODE $ila]"
  puts "  ADV_TRIGGER:[get_property STATIC.IS_ADVANCED_TRIGGER_MODE_SUPPORTED $ila]"
  puts "  TRIG_IN:[get_property STATIC.IS_TRIG_IN_SUPPORTED $ila]"
  puts "  CAPTURE_QUAL:[get_property STATIC.IS_BASIC_CAPTURE_MODE_SUPPORTED $ila]"
  puts "  STATUS:[get_property STATUS.CORE_STATUS $ila]"
  puts "  WINDOW_COUNT:[get_property CONTROL.WINDOW_COUNT $ila]"
  puts "  === PROBES ==="
  foreach p [get_hw_probes -of_objects $ila] {
    puts "  PROBE:$p WIDTH:[get_property PROBE_PORT_BIT_COUNT $p] TYPE:[get_property TYPE $p]"
  }
}

No ILA found → STOP. Guide: "No ILA cores detected. Ensure the device was programmed with a bitstream containing ILA cores and the correct .ltx probes file is associated."

On the chipscope-mcp fallback path:

• A zero-ILA reading before chipscope_scan(action="scan", ltx_path=...) has run is not authoritative — don't treat it as "no ILA found" yet.
• After scanning, if the server reports a debug_ready field, treat debug_ready: true as confirmation.
• If debug_ready is absent, fall back to the scan's own reported core count instead.

Step 2: Configure Trigger

Basic trigger — map user's NL request to probe compare values:

set ila [lindex [get_hw_ilas] 0]
# TRIGGER_MODE is read-only on Versal (axis_ila) — use catch to skip gracefully
catch {set_property CONTROL.TRIGGER_MODE BASIC_ONLY $ila}
set_property CONTROL.TRIGGER_CONDITION AND $ila
set_property CONTROL.TRIGGER_POSITION 512 $ila
set_property CONTROL.DATA_DEPTH 1024 $ila
set_property TRIGGER_COMPARE_VALUE eq1'b1 [get_hw_probes <probe_name> -of_objects $ila]

Compare value syntax: eq<width>'<radix><value> — see REFERENCE.md for full encoding (=, !=, <, >, R, F, B, N, X).

Advanced trigger (TSM) — for multi-phase triggers (e.g., AXI transactions). See REFERENCE.md for the full grammar, rejection rules, and worked examples:

1. Generate a .tsm file with state machine code
2. Write it using agent file tools
3. Set: set_property CONTROL.TRIGGER_MODE ADVANCED_ONLY $ila
4. Set: set_property CONTROL.TSM_FILE <path> $ila
5. Compile-check: run_hw_ila -compile_only $ila

Capture condition (storage qualifier):

set_property CONTROL.CAPTURE_MODE BASIC $ila
set_property CONTROL.CAPTURE_CONDITION AND $ila
set_property CAPTURE_COMPARE_VALUE eq1'b1 [get_hw_probes <probe> -of_objects $ila]

Step 3: Arm, Wait & Upload

run_hw_ila $ila
wait_on_hw_ila $ila
upload_hw_ila_data $ila

For immediate capture (no trigger, "aliveness" check):

run_hw_ila -trigger_now $ila
wait_on_hw_ila $ila
upload_hw_ila_data $ila

⚠️ `wait_on_hw_ila` blocks until trigger fires. If the trigger condition is never met, the agent will hang. For conditions that may not fire, use run_hw_ila -trigger_now first to verify probe connectivity.

⚠️ `wait_on_hw_ila -timeout N` is in MINUTES (not seconds). Use -timeout 1 for a 1-minute cap. Omitting -timeout waits indefinitely.

⚠️ Versal DPC arm latency. On Versal (axis_ila via DPC JTAG), there is a brief latency between run_hw_ila returning and the ILA hardware being fully armed. If the triggering event is driven by VIO in the same Vivado session, issue the commit_hw_vio that fires the trigger in a separate `vivado_execute` call — not in the same command as run_hw_ila. The natural inter-call latency (~100 ms) is sufficient for the ILA to settle into WAITING_FOR_TRIGGER state.

Step 4: Export & Analyze Data

write_hw_ila_data -csv_file vivado_agentic_ai_reports/hw-ila-debug/capture_data [upload_hw_ila_data $ila]

Export formats: -csv_file (spreadsheet), -vcd_file (waveform viewer), or native .ila (Vivado reload).

To read specific probe sample values programmatically:

list_hw_samples [get_hw_probes <probe_name> -of_objects $ila]

Step 5: Write Output Files — MANDATORY after every successful capture

This step is not optional and does not depend on the user asking for a report. Any prompt that results in a completed ILA capture — including "display captured data", "show the waveform", "upload and display", or "arm and capture" — MUST produce all three output files before any chat summary is given.

Write every file below under vivado_agentic_ai_reports/hw-ila-debug/. The file tool creates missing parent directories, so do not shell out to mkdir (this skill forbids terminal commands).

Prompt mapping — these user phrases all require files to be written before summarizing in chat:

After writing files, confirm in chat: "Files written to vivado_agentic_ai_reports/hw-ila-debug/: capture_data.csv, report_data.json, REPORT.md."

Where to find the report: vivado_agentic_ai_reports/hw-ila-debug/REPORT.md in the working directory where the agent session was started. If the report was not generated, the capture data is still uploaded (from Step 3) — write the output files from that existing upload without re-arming. Only retry from Step 3 if the capture itself failed (e.g. trigger never fired, upload returned no samples).

Design-Specific Rules

All outputs MUST use ACTUAL values.

Error Handling

Examples

"Capture whatever is on the ILA right now" → Discover ILA → run_hw_ila -trigger_now → wait_on_hw_ila → upload_hw_ila_data → export CSV → summarize.

"Trigger when AXI RVALID goes high" → Find probe for axi_rvalid → set_property TRIGGER_COMPARE_VALUE eq1'b1 → arm → wait → upload → export.

"Trigger on AXI read transaction (address then data then last)" → Generate 3-state TSM → write .tsm file → set ADVANCED_ONLY → arm → capture.

Chipscope-mcp Fallback