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

VIO Debug (EA)

Early Access — this skill may change before general availability.

Interacts with VIO debug cores on live hardware: discover → read inputs → drive outputs → monitor activity.

See REFERENCE.md for VIO property tables and Tcl command reference.

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_vio) 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_vio. 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 VIO cores in one vivado_execute, not separate calls.
• Write reports to file — do not dump full probe data in chat. Give a short summary only.
• Use `vivado_doc_search` for unfamiliar probe properties.
• 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.

Monitor & Control Workflow

Step 1: Discover VIO Cores & Probes

puts "=== VIO CORES ==="
foreach vio [get_hw_vios] {
  puts "VIO:$vio INSTANCE:[get_property INSTANCE_NAME $vio] REFRESH:[get_property CORE_REFRESH_RATE_MS $vio]"
  puts "  === INPUT PROBES ==="
  foreach p [get_hw_probes -of_objects $vio -filter {TYPE == vio_input}] {
    refresh_hw_vio $vio
    puts "  IN:$p VALUE:[get_property INPUT_VALUE $p] ACTIVITY:[get_property ACTIVITY_VALUE $p]"
  }
  puts "  === OUTPUT PROBES ==="
  foreach p [get_hw_probes -of_objects $vio -filter {TYPE == vio_output}] {
    puts "  OUT:$p VALUE:[get_property OUTPUT_VALUE $p]"
  }
}

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

⚠️ After programming or reprogramming, VIO output probe software values may retain stale values from the previous session. Always sync before driving outputs:

refresh_hw_vio -update_output_values [get_hw_vios hw_vio_1]

or reset all outputs to design-time initial values:

reset_hw_vio_outputs [get_hw_vios hw_vio_1]

This ensures the software state matches hardware, so that subsequent set_property OUTPUT_VALUE + commit_hw_vio creates proper signal transitions (e.g., 0→1 edges for pulse-triggered designs).

Step 2: Read Input Values

refresh_hw_vio [get_hw_vios hw_vio_1]
foreach p [get_hw_probes -of_objects [get_hw_vios hw_vio_1] -filter {TYPE == vio_input}] {
  puts "$p INPUT:[get_property INPUT_VALUE $p] ACTIVITY:[get_property ACTIVITY_VALUE $p]"
}

Step 3: Drive Output Values

Map user's NL request to probe + value:

set_property OUTPUT_VALUE 1 [get_hw_probes <probe_name> -of_objects [get_hw_vios hw_vio_1]]
commit_hw_vio [get_hw_vios hw_vio_1]

Reset all outputs to initial values:

reset_hw_vio_outputs [get_hw_vios hw_vio_1]

Clear activity detectors:

reset_hw_vio_activity [get_hw_vios hw_vio_1]

Step 4: Write Output Files

⚠️ Write ALL files before giving any summary. Use agent file tools.

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

Design-Specific Rules

All outputs MUST use ACTUAL values.

Error Handling

Examples

"What is the VIO reset signal?" → Discover VIO → refresh_hw_vio → read INPUT_VALUE of reset probe → report value + activity.

"Assert reset for 1 cycle" → set_property OUTPUT_VALUE 1 on reset probe → commit_hw_vio → set_property OUTPUT_VALUE 0 → commit_hw_vio.

Chipscope-mcp Fallback

Use this path only when Vivado MCP is not installed. Session lifecycle per VIVADO-PATTERNS.md Pattern 19 (vivado-skill-creator):

chipscope_session(action="connect", hw_server_url="TCP:<host>:3121", cs_server_url="TCP:<host>:3042")
chipscope_device(action="select", device_selector="0")
chipscope_scan(action="scan", ltx_path="<path-to-design>.ltx")

VIO — read inputs:

chipscope_vio(action="read", vio_name="<vio-name>")

VIO — drive outputs: ALWAYS write every output probe of the VIO in one `write` call.

Some chipscope-mcp versions write only the probes you name. After programming, a write that names only some outputs can leave the VIO's other outputs driving wrong values and stall the design. The tool still returns success, and the readback shows the value you asked for. Writing every output in one call is correct on every version, with or without the fix.

1. List the VIO's output probes (entries with direction "out"):

`` chipscope_vio(action="probes", vio_name="<vio-name>") ``

1. Read their current values:

`` chipscope_vio(action="read", vio_name="<vio-name>", probes=["<out1>", "<out2>", ...]) ``

1. Write all of them in one call. Change only what the user asked for; pass the current value for every other output:

`` chipscope_vio(action="write", vio_name="<vio-name>", probe_values={"<out1>": <current>, "<out2>": <new>, ...}) ``

1. Confirm the change through an input probe the output drives (value moving, direction, activity). Do not use the write readback as proof.

• A pulse (assert, then deassert) is two write calls, each with every output.
• action="ports_write" has the same problem. If you use it, pass every probe_out<N> port.
• action="reset" restores initial values but does not prevent this. Still write every output afterwards.
• If the design already stalled after a partial write, one write of every output recovers it.

Exact action/parameter names must be confirmed against the live chipscope-mcp tool schema before use — do not assume the names above are final without checking chipscope-mcp/src/chipscope_mcp/tools/chipscope_vio.py.

NEVER auto-program PDI. Stop and ask before chipscope_device(action="program").

Integration

Complementary: Drives stimulus for hw-ila-debug capture (combined debug session)

Metadata

Keywords: VIO, probe, input, output, activity, monitor, drive, reset