open-vivado

name	open-vivado
description	Use when the task requires command-line control of AMD Vivado through the local bridge, including starting the bridge, sending structured Vivado commands, checking runtime state, and stopping the bridge.

Open Vivado

Use this skill for command-line Vivado automation through the local bridge.

CLI entrypoints

• python3 skills/open-vivado/scripts/bridge.py start
• python3 skills/open-vivado/scripts/bridge.py restart
• python3 skills/open-vivado/scripts/bridge.py status
• python3 skills/open-vivado/scripts/bridge.py send --command <name> [--args '<json>'] [--timeout-ms <ms>]
• python3 skills/open-vivado/scripts/bridge.py stop

Bridge CLI parameters

start

Command:

python3 skills/open-vivado/scripts/bridge.py start [options]

Options:

• --vivado-bin <path>: explicit Vivado executable path.
• --python-bin <path>: Windows only; explicit Vivado-bundled Python path.
• --port <int>: override the socket port.
• --timeout-ms <int>: startup wait timeout in milliseconds.
• --unsafe: enable unsafe Tcl mode. Do not use unless raw Tcl execution is required.
• --config-dir <path>: override config directory. Default is ~/.config/open-vivado.

Exit codes: 0 = ready, 3 = started but socket not yet ready, 4 = lock conflict (another bridge is running).

WSL note: if XILINX_VIVADO points to a Windows-mounted path (/mnt/c/…), the bridge automatically ignores it and falls back to scanning /opt for a native Linux Vivado. Pass --vivado-bin explicitly to override.

restart

Command:

python3 skills/open-vivado/scripts/bridge.py restart [options]

Behavior:

• Stops any running or stale bridge process, clears all locks, then starts a fresh bridge.
• Accepts the same options as start (--vivado-bin, --port, --timeout-ms, --unsafe).
• Use instead of the manual stop → unlock → start sequence.

status

Command:

python3 skills/open-vivado/scripts/bridge.py status [--config-dir <path>]

Behavior:

• Reads runtime state from the config directory.
• Returns running, stale, or stopped.

send

Command:

python3 skills/open-vivado/scripts/bridge.py send --command <name> [options]

Options:

• --command <name>: required command name.
• --args '<json>': JSON object string for command parameters.
• --timeout-ms <int>: request timeout in milliseconds.
• --host <host>: override runtime host.
• --port <int>: override runtime port.
• --mode safe|unsafe: defaults to safe. Use unsafe only when the bridge was started with --unsafe.
• --config-dir <path>: override config directory.

stop

Command:

python3 skills/open-vivado/scripts/bridge.py stop [--config-dir <path>]

Behavior:

• Stops the tracked Vivado bridge process.
• Clears the saved runtime state.

unlock

Command:

python3 skills/open-vivado/scripts/bridge.py unlock [--force]

Behavior:

• Clears stale startup lock files.
• Refuses to unlock active locks by default.
• --force only unlocks non-current active lock PIDs; it still refuses unlocking the current live runtime lock.

Quick start

1. Start the bridge:

   python3 skills/open-vivado/scripts/bridge.py start
   

2. Verify connectivity:

   python3 skills/open-vivado/scripts/bridge.py send --command ping
   python3 skills/open-vivado/scripts/bridge.py send --command get_version
   

3. Run Vivado commands:

   python3 skills/open-vivado/scripts/bridge.py send --command create_project \
     --args '{"name":"proj","path":"/tmp/proj","part":"xc7a35tcpg236-1"}'
   
   python3 skills/open-vivado/scripts/bridge.py send --command add_source_file \
     --args '{"file":"/path/to/design.v"}'
   
   python3 skills/open-vivado/scripts/bridge.py send --command add_constraint_file \
     --args '{"file":"/path/to/constraints.xdc"}'
   
   python3 skills/open-vivado/scripts/bridge.py send --command set_top_module \
     --args '{"top":"top_module"}'
   

4. Run build steps:

   python3 skills/open-vivado/scripts/bridge.py send --command launch_synthesis \
     --args '{"jobs":"4"}' --timeout-ms 120000
   python3 skills/open-vivado/scripts/bridge.py send --command wait_synthesis \
     --args '{"poll_interval_ms":"5000"}' --timeout-ms 3600000
   python3 skills/open-vivado/scripts/bridge.py send --command launch_implementation \
     --args '{"jobs":"4"}' --timeout-ms 120000
   python3 skills/open-vivado/scripts/bridge.py send --command wait_implementation \
     --args '{"poll_interval_ms":"5000"}' --timeout-ms 3600000
   python3 skills/open-vivado/scripts/bridge.py send --command generate_bitstream \
     --args '{"jobs":"4"}' --timeout-ms 300000
   

5. Query reports or state as needed:

   python3 skills/open-vivado/scripts/bridge.py send --command report_utilization
   python3 skills/open-vivado/scripts/bridge.py send --command get_timing_summary
   python3 skills/open-vivado/scripts/bridge.py send --command check_timing \
     --args '{"format":"json"}'
   python3 skills/open-vivado/scripts/bridge.py send --command report_drc
   python3 skills/open-vivado/scripts/bridge.py status
   

6. Stop the bridge when done:

   python3 skills/open-vivado/scripts/bridge.py stop
   

Incremental build workflow

Use incremental compilation to speed up re-runs after small RTL changes:

1. Complete a full build and save a reference checkpoint:

   python3 skills/open-vivado/scripts/bridge.py send --command write_checkpoint \
     --args '{"file":"/path/to/reference.dcp"}'
   

2. Make RTL changes, then launch incremental synthesis:

   python3 skills/open-vivado/scripts/bridge.py send --command launch_synthesis \
     --args '{"jobs":"4","incremental":"true"}' --timeout-ms 120000
   python3 skills/open-vivado/scripts/bridge.py send --command wait_synthesis \
     --args '{"poll_interval_ms":"5000"}' --timeout-ms 3600000
   

3. Launch incremental implementation with the reference checkpoint:

   python3 skills/open-vivado/scripts/bridge.py send --command launch_implementation \
     --args '{"jobs":"4","incremental":"true","reference_checkpoint":"/path/to/reference.dcp"}' \
     --timeout-ms 120000
   python3 skills/open-vivado/scripts/bridge.py send --command wait_implementation \
     --args '{"poll_interval_ms":"5000"}' --timeout-ms 3600000
   

4. Compare results against the baseline:

   python3 skills/open-vivado/scripts/bridge.py send --command compare_last_two_builds
   

Safe-mode command reference

All commands below are sent through:

python3 skills/open-vivado/scripts/bridge.py send --command <name> --args '<json>'

If a command has no parameters, omit --args.

Project commands

create_project

• Required JSON fields:
  • name: project name.
  • path: project directory path.
  • part: FPGA part name, for example xc7a35tcpg236-1.
• Optional JSON fields:
  • force: "true" to overwrite an existing project directory.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command create_project \
  --args '{"name":"proj","path":"/tmp/proj","part":"xc7a35tcpg236-1","force":"true"}'

open_project

• Required JSON fields:
  • path: path to the .xpr project file.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command open_project \
  --args '{"path":"/work/demo/demo.xpr"}'

close_project

• Parameters: none.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command close_project

get_project_info

• Parameters: none.
• Returns project name, part, directory, and top module if available.

add_source_file

• Required JSON fields:
  • file: source file path.
• Optional JSON fields:
  • fileset: target fileset name. Default is sources_1.
• Supports HDL source types managed by Vivado, including Verilog, SystemVerilog, and VHDL.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command add_source_file \
  --args '{"file":"/path/to/design.v","fileset":"sources_1"}'

add_constraint_file

• Required JSON fields:
  • file: XDC file path.
• Adds the file to constrs_1.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command add_constraint_file \
  --args '{"file":"/path/to/constraints.xdc"}'

set_top_module

• Required JSON fields:
  • top: top-level module or entity name.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command set_top_module \
  --args '{"top":"top_module"}'

list_source_files

• Parameters: none.
• Returns newline-separated source file paths.

list_constraint_files

• Parameters: none.
• Returns newline-separated constraint file paths from constrs_1.

list_ports

• Optional JSON fields:
  • direction: filter by port direction: IN, OUT, INOUT, or all (default).
• Returns newline-separated port names.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command list_ports \
  --args '{"direction":"IN"}'

Build commands

launch_synthesis

• Optional JSON fields:
  • jobs: parallel job count. Default behavior uses Vivado's plain launch_runs synth_1.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command launch_synthesis \
  --args '{"jobs":"4"}' --timeout-ms 120000

wait_synthesis

• Polls synth_1 status until completion. Does not block the Tcl event loop.
• Optional JSON fields:
  • poll_interval_ms: polling interval in milliseconds. Default is 5000.
  • timeout_ms: hard timeout ceiling in milliseconds. Default is 3600000 (1 hour).
• Returns run status string on completion. Returns an error if the timeout is exceeded.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command wait_synthesis \
  --args '{"poll_interval_ms":"3000"}' --timeout-ms 3600000

get_synthesis_status

• Parameters: none.
• Returns current synth_1 status and progress without blocking.

open_synthesis_run

• Parameters: none.
• Opens synth_1 results in Vivado.

reset_run

• Resets a synthesis or implementation run so it can be re-executed.
• Optional JSON fields:
  • run: run name to reset. Default is impl_1.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command reset_run \
  --args '{"run":"synth_1"}'

launch_implementation

• Optional JSON fields:
  • jobs: parallel job count. Default behavior uses Vivado's plain launch_runs impl_1.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command launch_implementation \
  --args '{"jobs":"4"}' --timeout-ms 120000

wait_implementation

• Polls impl_1 status until completion. Does not block the Tcl event loop.
• Optional JSON fields:
  • poll_interval_ms: polling interval in milliseconds. Default is 5000.
  • timeout_ms: hard timeout ceiling in milliseconds. Default is 3600000 (1 hour).
• Returns run status string on completion. Returns an error if the timeout is exceeded.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command wait_implementation \
  --args '{"poll_interval_ms":"5000"}' --timeout-ms 3600000

get_implementation_status

• Parameters: none.
• Returns current impl_1 status and progress without blocking.

open_implementation_run

• Parameters: none.
• Opens impl_1 results in Vivado.

Run property commands

get_run_property

• Required JSON fields:
  • property: property name, for example STATUS, STRATEGY, STEPS.PHYS_OPT_DESIGN.IS_ENABLED.
• Optional JSON fields:
  • run: run name. Default is impl_1.
• Returns the property value as a string.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command get_run_property \
  --args '{"property":"STRATEGY","run":"impl_1"}'

set_run_property

• Required JSON fields:
  • property: property name.
  • value: new property value.
• Optional JSON fields:
  • run: run name. Default is impl_1.
• Commonly used properties:
  • STRATEGY: synthesis/implementation strategy name.
  • STEPS.PHYS_OPT_DESIGN.IS_ENABLED: enable physical optimization (1/0).
  • STEPS.PLACE_DESIGN.ARGS.DIRECTIVE: placement directive.
  • STEPS.ROUTE_DESIGN.ARGS.DIRECTIVE: routing directive.
  • INCREMENTAL_CHECKPOINT: path to reference checkpoint for incremental implementation.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command set_run_property \
  --args '{"property":"STEPS.PHYS_OPT_DESIGN.IS_ENABLED","value":"1","run":"impl_1"}'

Report commands

report_utilization

• Parameters: none.
• Returns the raw report_utilization text.
• Extended JSON args:
  • filter: set to high to keep only high-utilization resources.
  • threshold: utilization threshold percentage used with filter=high.

report_timing_summary

• Parameters: none.

• Returns the raw report_timing_summary text.

• Extended JSON args activate local parsing when any of the following are present:

  • format: set to json for parsed JSON output (summary + violations).
  • raw: set to "true" to force raw Vivado text even when format=json is set.
  • summary_only: set to "true" to return only the parsed timing summary dict, no violations.
  • violations_only: set to "true" to return only violating paths (delegates to get_timing_violations).
  • max_paths: max violation paths to include. Default is 10.
  • exclude_met_paths: set to "true" (default) to hide met paths in parsed output.
  • report_file: path to save the full raw timing text alongside parsed output.

  format	raw	violations_only	summary_only	Output
  —	—	—	—	raw Vivado text
  json	—	—	—	{summary, violations} JSON
  json	true	—	—	raw Vivado text
  —	—	true	—	violations list only
  —	—	—	true	summary dict only

report_drc

• Parameters: none.
• Returns the raw report_drc text.

check_timing

• Runs Vivado's check_timing to identify unconstrained clocks, inputs without delay, outputs without delay, and other timing issues.
• Optional JSON fields:
  • format: set to json to return a structured dict instead of raw text.
• Structured output fields (format=json):
  • checks: {check_name: {count, description}} for each check category.
  • no_clock: count of register pins with no clock.
  • unconstrained_inputs: count of input ports with no input delay.
  • unconstrained_outputs: count of output ports with no output delay.
  • has_issues: true if any check has a non-zero count.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command check_timing \
  --args '{"format":"json"}'

report_methodology

• Runs Vivado's report_methodology to surface methodology rule violations (timing, CDC, power).
• Optional JSON fields:
  • format: set to json to return a structured dict instead of raw text.
• Structured output fields (format=json):
  • total: total number of violations found.
  • by_rule: {rule_id: count} mapping.
  • violations: list of {rule, message} objects (up to 100).
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command report_methodology \
  --args '{"format":"json"}'

get_timing_summary

• Parameters: none.
• Returns compact parsed timing data without re-running a full report:
  • No violation: returns summary only.
  • Violation exists: returns summary plus violations paths.
• If a run had to be opened automatically, the result includes design_opened.

get_last_timing_summary

• Parameters: none.
• Returns timing data from the most recently stored snapshot without calling Vivado.
• Useful for automation that needs WNS/TNS/failing-endpoints after a completed build without re-running parsers.
• Returns label, created_at, timing, and clocks from the snapshot.
• Returns an error if no snapshots exist yet.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command get_last_timing_summary

get_timing_violations

• Optional JSON fields:
  • max_paths: maximum number of violating paths to return. Default is 10.
  • clocks: comma-separated clock names to filter violations by (e.g. "userclk2,clk_125mhz").
  • path_groups: comma-separated path group names to filter violations by.
• Example (filter to a single clock domain):

python3 skills/open-vivado/scripts/bridge.py send --command get_timing_violations \
  --args '{"max_paths":"20","clocks":"userclk2"}'

report_timing_by_clock

• Required JSON fields:
  • clock: clock name to analyze.
• Optional JSON fields:
  • max_paths: maximum number of paths to return. Default is 10.
  • format: set to json to return parsed {summary, violations, clocks} instead of raw text.
• Example (structured output):

python3 skills/open-vivado/scripts/bridge.py send --command report_timing_by_clock \
  --args '{"clock":"userclk2","max_paths":"5","format":"json"}'

generate_all_reports

• Optional JSON fields:
  • output_dir: directory to write reports.json.
  • label: snapshot label used by compare commands.
• Returns a structured snapshot including timing, utilization, DRC excerpt, clocks, and power when available.
• Snapshots are automatically evicted after the 20 most recent are stored.

report_power

• Parameters: none.
• Returns parsed power summary JSON.

Artifact commands

generate_bitstream

• Optional JSON fields:
  • jobs: parallel job count for launch_runs impl_1 -to_step write_bitstream.
• Runs launch_runs impl_1 -to_step write_bitstream, which re-runs the implementation run through the write_bitstream step. If implementation already completed cleanly, Vivado will skip unchanged steps; otherwise it re-executes from the last incomplete step.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command generate_bitstream \
  --args '{"jobs":"4"}' --timeout-ms 300000

write_checkpoint

• Required JSON fields:
  • file: output checkpoint path, usually ending with .dcp.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command write_checkpoint \
  --args '{"file":"/path/to/design.dcp"}'

read_checkpoint

• Required JSON fields:
  • file: checkpoint path to load.

export_hardware

• Exports a hardware platform file (.xsa) for use with Vitis or PetaLinux.
• Required JSON fields:
  • file: output .xsa file path.
• Optional JSON fields:
  • bitstream: "true" to include the bitstream in the exported platform.
• Example:

python3 skills/open-vivado/scripts/bridge.py send --command export_hardware \
  --args '{"file":"/path/to/design.xsa","bitstream":"true"}'

Constraint and comparison commands

list_timing_constraints

• Parameters: none.
• Reads current XDC files and returns create_clock, set_false_path, set_input_delay, and set_output_delay lines.

add_timing_constraint

• Required JSON fields:
  • type: one of clock, false_path, input_delay, output_delay.
• Additional fields by type:
  • clock: name, period, optional port, optional file.
  • false_path: from, to, optional file.
  • input_delay: clock, delay, port, optional file.
  • output_delay: clock, delay, port, optional file.
• If file is omitted, the first existing constraint file is used.

check_constraint_coverage

• Parameters: none.
• Returns coarse counts for create_clock, set_false_path, set_input_delay, and set_output_delay.

suggest_constraints

• Parameters: none.
• Returns constraint suggestions based on current XDC coverage and live design data.
• Uses actual clock names from get_clocks and port names from list_ports to produce concrete, actionable suggestions rather than generic templates.
• Result includes coverage, clocks (current clock periods), and suggestions list.

compare_timing

• Optional JSON fields:
  • baseline: stored snapshot label.
  • current: stored snapshot label.
• Without labels, the current live design snapshot is used.

compare_utilization

• Optional JSON fields:
  • baseline: stored snapshot label.
  • current: stored snapshot label.

compare_power

• Optional JSON fields:
  • baseline: stored snapshot label.
  • current: stored snapshot label.

get_clocks

• Parameters: none.
• Returns one line per defined clock with tab-separated fields: name, period, frequency_mhz, waveform, is_generated.
• Requires an open project with synthesis or implementation results loaded. Returns an informative warning message (not an error) when the project is open but no run is loaded yet.

Runtime and diagnostics commands

set_power_opt

• Optional JSON fields:
  • strategy: bridge preference such as low, default, or high.
• Stores a bridge-side power optimization preference for later build orchestration.

get_incremental_status

• Parameters: none.
• Returns the last tracked incremental build request.

list_checkpoints

• Parameters: none.
• Recursively lists .dcp files under the current project directory.

compare_checkpoints

• Required JSON fields:
  • baseline: baseline checkpoint path.
  • current: current checkpoint path.
• Compares file size, timestamp, and content hash.

set_language

• Required JSON fields:
  • lang: language tag such as zh_CN or en_US.

get_build_stats

• Parameters: none.
• Returns the latest recorded synthesis, implementation, and bitstream durations from bridge history.

analyze_build_trends

• Optional JSON fields:
  • commits: number of recent history samples to average. Default is 10.

compare_last_two_builds

• Parameters: none.
• Compares timing and utilization deltas between the last two stored report snapshots.

timing_trend

• Optional JSON fields:
  • last_n: number of recent snapshots to include. Default is 5.
• Returns per-build timing/utilization trend rows.

diagnose_timing_violation

• Optional JSON fields:
  • path_index: zero-based index into the current violation list. Default is 0.
• Returns severity-classified guidance with path-specific suggestions.
• Severity is calculated relative to the failing clock's period:
  • critical: violation exceeds 20% of clock period.
  • moderate: violation exceeds 8% of clock period.
  • minor: violation is less than 8% of clock period.
  • Falls back to absolute ns thresholds (-2.0 / -0.5) if clock period is unavailable.
• Result includes clock_period_ns when the clock period was resolved.

Notes

• Most commands require an open project.
• Use JSON strings for --args.
• Treat outputs prefixed with ERROR: or CRITICAL: as hard failures.
• Bridge startup uses a lock file in ~/.config/open-vivado/bridge_start.lock.json to prevent duplicate Vivado launches. Exit code 4 means a lock conflict; use restart or stop + unlock to recover.
• WSL: XILINX_VIVADO pointing to a Windows-mounted path (/mnt/<drive>/…) is automatically ignored with a warning; the bridge falls back to scanning /opt for a native Linux Vivado.
• wait_synthesis and wait_implementation use non-blocking polling (Python-side) and will not cause the Tcl event loop to stall. The --timeout-ms passed to send must be larger than args.timeout_ms to avoid a client-side timeout before the run finishes.
• Report snapshots are capped at 20 entries; the oldest are evicted automatically.
• Development-oriented documentation lives under doc/.