full-flow-demo

name

full-flow-demo

description

Drive a Xilinx FPGA design end-to-end through the complete build flow: RTL -> simulation -> synthesis -> implementation -> bitstream, with a verification gate after every stage so a downstream stage never runs on an upstream stage that silently regressed. Invoke this skill when the user says "rtl to bitstream", "end to end", "full flow", "run everything", "build the whole thing", "take this design all the way to a .bit", "complete build", or asks to drive a project from source files to a programmed/exportable bitstream in one orchestrated pass. Requires the SynthPilot MCP server connected to an open Vivado session with the Tcl server (tcl_server.tcl on TCP:9999) running. This is the ORCHESTRATION playbook: it sequences the real flow tools, gates each stage on fresh tool evidence, stops on the first real failure, and hands off to the specialist skills (timing-closure, cdc-analysis, lint, simulation-debug) instead of trying to fix violations itself.

Full-Flow Demo: RTL -> Sim -> Synth -> Impl -> Bitstream

You are orchestrating a complete FPGA build. Your job is sequencing and gating, not problem-solving. You run each stage, then prove with a fresh tool report that the stage actually passed before unlocking the next stage. The flow is a pipeline of gates: a green stage opens the next gate; a red stage stops the flow and hands the specific failure to the right specialist skill.

The single most important rule: a bitstream is not "done" because generate_bitstream returned. The implemented design must pass post-route signoff — setup AND hold timing met, DRC clean, route status fully routed, methodology clean — and that signoff must run on the open implemented design before you write the bitstream. Synthesis numbers are necessary but never sufficient.

---

When to use

• User wants a design taken from source files all the way to a .bit (or .xsa / .mcs) in one orchestrated pass: "rtl to bitstream", "full flow", "run everything", "end to end".
• You have (or will create) a Vivado project with sources, constraints, and a known top module and target part.
• The user wants stage-by-stage gating and a final signoff summary they can trust, rather than a single black-box run_full_flow call.

When NOT to use

• A single stage is the actual problem. If the user says "fix my timing", "why does synthesis fail", "is my CDC clean", "my sim is wrong" — go straight to the specialist skill (timing-closure, synthesis-debug, cdc-analysis, simulation-debug, lint). This skill calls into those; it does not replace them.
• No project / no Vivado connection yet. Resolve prerequisites first.
• The design is a Block Design / Zynq / MPSoC system that has not yet been validated, generated, and wrapped. Do the BD bring-up first (bd_validate_design -> bd_generate_output_and_wrapper -> set_top_module <wrapper>), then return here for synth -> bitstream.
• The user wants speed over safety ("just slam it through, I don't care about checks"). You may use run_full_flow as a fast path, but you must still run the post-route signoff gate (Stage 5) before claiming success. Never skip that gate.

---

Prerequisites (verify first)

Run these before touching the flow. Do not assume; confirm with tool output.

1. MCP / Vivado / Tcl server alive — test_connection. If it fails, stop and tell the user to open Vivado and start tcl_server.tcl (TCP:9999). Nothing below works without this.
2. A project is open with a known target part — get_project_info. Confirm project name, part number, and current top module are what the user expects. If no project is open: open_project (existing) or create_project
   • add_source_file / add_constraint_file (new).
3. Top module is set and correct — confirm via get_project_info; fix with set_top_module if wrong. A wrong top silently synthesizes the wrong thing.
4. Sources and constraints are present and in order — list_source_files, list_constraint_files. A flow with zero constraint files will "pass" timing vacuously (no clocks defined) — treat "0 constraints" as a hard stop, not a pass. If compile order is suspect, check_compile_order.
5. License tier permits the full flow — get_license_status. Async runs, advanced reports, and some IP/BD tools are PRO/MAX. If FREE, fall back to the synchronous basic path and tell the user which gates you cannot run.

Record the baseline: part, top, clock constraints present (get_all_clocks after a design is open), and intended target frequency. You will measure the final result against this.

---

Methodology (numbered, gated)

Run stages in order. After each stage, the gate must pass on fresh tool output or you STOP and route to the specialist. One stage at a time so cause -> effect stays attributable.

Stage ordering is signoff-before-bitstream. The post-route signoff gate (Stage 5) runs on the open implemented design and proves setup/hold timing, routing, DRC, and methodology are all clean before generate_bitstream is ever called (Stage 6). You never write a bitstream on an unverified implemented design. After the bitstream is written, a short re-confirmation read (Stage 6's gate) checks the write itself and that signoff still holds.

Fast path note: run_full_flow runs synthesis -> implementation -> bitstream in one call with per-stage timing and early-stop-on-failure. It is acceptable when the user wants speed AND the design has already passed lint/sim. It does not replace the post-route signoff gate. Because run_full_flow writes the bitstream inside the same call, if you use it you must immediately open_implemented_design and run the full Stage 5 signoff evidence gate afterward; only a green Stage 5 result licenses a PASS verdict.

Stage 0 — Static checks (cheap, before any long run)

Catch dumb errors before burning minutes on synthesis.

• check_syntax (or check_syntax_file per file) — must be clean.
• run_quick_lint for a fast structural pass; escalate to run_full_lint_check if the user wants thoroughness. Triage with get_lint_violations.
• Targeted structural checks as relevant: check_latches (unintended latches), check_async_reset, check_fsm, check_port_width_mismatch, check_unconnected_ports, check_black_box.

GATE 0: No syntax errors. No error-severity lint/structural findings (unintended latch, width mismatch, missing module / black box, broken compile order). Warnings may pass with a noted assumption.

• If it fails: STOP. Hand to the lint skill. Do not waive_lint_violation or disable_lint_rule to make the count go green — see Safety rails.

Stage 1 — Functional simulation (does the RTL do the right thing?)

Synthesizing functionally-broken RTL wastes an hour. Simulate first when a testbench exists.

• Confirm the TB: list_simulation_files; set the sim top with set_simulation_top if needed.
• Compile: sim_compile (pass top_module). On failure read sim_get_compile_log.
• Run. Multi-minute sims: use the async pattern — sim_run_async, then poll sim_get_sim_status until COMPLETED (or sim_stop to abort). Short sims: sim_run.
• Read results with sim_get_report. Inspect waveforms/values via sim_list_signals + sim_probe if the pass/fail is ambiguous.

GATE 1: Testbench reports PASS (self-checking TB, expected $finish, no assertion/$error/mismatch). If there is no testbench, state that explicitly as a risk ("proceeding to synthesis without functional verification") and ask the user whether to continue.

• If it fails: STOP. Hand to the simulation-debug skill. A failing sim is an RTL bug; do not "fix" it by changing constraints downstream.

Stage 2 — CDC sanity (before committing to a build)

Clock-domain-crossing bugs do not show up in timing or DRC and survive to silicon.

• check_cdc_lint as an early RTL-level pass. A fuller report_cdc needs an elaborated/synthesized design and is run again — and gated — in Stage 3.

GATE 2: No critical (unsynchronized / glitch-prone) CDC findings at the RTL level.

• If it fails: STOP. Hand to the cdc-analysis skill. Do not set_false_path across a crossing to silence it unless you can state the assumption that it is genuinely async-safe and the user agrees — silencing a real CDC is a fake-pass.

Stage 3 — Synthesis

• (Optional) pick a strategy with set_synthesis_strategy — default is fine for a first pass; smallest change first.
• Run. Multi-minute: async — run_synthesis_async, poll get_run_status until the synth run STATUS shows complete (watch PROGRESS reach 100%). Short: run_synthesis.
• Open the result for analysis: open_synthesized_design.
• Evidence: get_synthesis_report, get_synthesis_warnings, check_synthesis_issues (needs the design open). Confirm clocks exist: get_all_clocks. Sanity-check report_utilization (a synth util that already exceeds 100% of any resource means impl cannot succeed — stop early).
• Re-run report_cdc now that there is a real netlist — synthesis can introduce or expose crossings the RTL-level check_cdc_lint did not see.

GATE 3: All of the following on fresh output:

• Synth run COMPLETE (not ERROR), no error-level synth warnings.
• At least one clock constraint present (get_all_clocks non-empty).
• Utilization physically fits the part (report_utilization under 100% on every resource).
• Post-netlist CDC clean — report_cdc shows no critical / unsafe (unsynchronized, glitch-prone, fan-out) crossings. A crossing introduced or revealed by synthesis is a STOP, not a warning to skip.

Post-synth timing is indicative only — do not claim "timing met" here.

• If it fails: STOP. Synth errors -> synthesis-debug skill. Post-netlist CDC findings -> cdc-analysis skill. Util overflow -> tell the user the design does not fit this part (architectural, not a constraint fix).

Stage 4 — Implementation (opt -> place -> route)

• (Optional) set_implementation_strategy (e.g., a Performance/Explore strategy) only if a first default pass missed timing — smallest change first, so do the default first.
• Run. Almost always multi-minute: async — run_implementation_async, poll get_run_status until impl_1 STATUS shows route_design Complete. Short designs: run_implementation.
• open_implemented_design so the Stage 5 signoff reports read the routed design.

GATE 4: Impl run COMPLETE (route_design did not error or abort).

• If it fails to route / errors: STOP. Capture get_implementation_warnings and report_congestion; route placement/congestion/timing-driven-routing failures to the timing-closure skill (it owns strategy/floorplan/RTL remediation). Do not blindly bump strategies in a loop.

Stage 5 — Post-route SIGNOFF gate (the gate that licenses "done") — runs BEFORE the bitstream

This gate must pass on the open implemented design BEFORE any bitstream is written. A failure here means the design is not signoff-clean; writing a bitstream is pointless (and generate_bitstream would re-run DRC and refuse anyway). Run on the open implemented design (open_implemented_design) with fresh reports:

• Timing: extract_timing_metrics (WNS/TNS/WHS/THS, failing endpoints) — you need both setup (WNS/TNS) and hold (WHS/THS) numbers across all clock groups. check_timing to confirm there are no unconstrained paths or missing-clock issues hiding the real picture.
• Routing: report_route_status — design must be 100% routed, zero unrouted nets.
• DRC: report_drc — zero error/critical violations. (DRC must be clean here, before the bitstream, because generate_bitstream reruns DRC and will refuse to write on errors.)
• Methodology: report_methodology — no critical methodology warnings (these flag CDC/timing-exception abuse the other reports miss).
• (Recommended) Power: report_power for a thermal/budget sanity number.

GATE 5 (signoff): ALL of the following must be true simultaneously on fresh post-route output, or you STOP:

• Setup met on every clock group: WNS ≥ 0 (equivalently TNS = 0).
• AND hold met on every clock group: WHS ≥ 0 (equivalently THS = 0). Setup-clean does not excuse a hold failure and vice-versa — both must pass at the same time.
• AND route status is 100% routed (zero unrouted nets).
• AND DRC clean (no error/critical violations).
• AND methodology clean (no critical warnings).

Only when every one of these is green on fresh output may you proceed to write the bitstream.

• If timing fails (setup OR hold < 0): STOP. Hand to the timing-closure skill with the extract_timing_metrics / analyze_critical_paths evidence. Do not set_false_path / set_multicycle_path to clear a real violation.
• If DRC/methodology fails: STOP and surface the specific rule IDs. Do not waive without an explicit user-approved assumption.

Stage 6 — Bitstream generation + final re-confirmation

Reach this stage only after Stage 5's signoff gate is fully green. The design is already proven signoff-clean; this stage writes the artifact and re-confirms nothing regressed in the write.

• generate_bitstream (synchronous; it launches impl_1 -to_step write_bitstream and waits). If you took the run_full_flow fast path, the bitstream was written inside that call — in which case you ran Stage 5's signoff gate after the call; treat that signoff result as Stage 5 and this stage's re-confirmation together.

GATE 6 (write + re-confirm):

• Bitstream write reported success and a .bit path is returned.
• A final read still shows the implemented design signoff-clean: re-confirm with report_route_status (still 100% routed) and report_drc (still 0 errors) on the open implemented design. (generate_bitstream runs its own DRC; a successful write plus these reads is the final proof.)
• If the write fails (e.g., DRC blocks it): STOP. This is a real signoff failure — return to Stage 5's DRC handling, not a workaround. (This should be rare, since Stage 5 already verified DRC.)

Stage 7 — Handoff artifacts (only after Gate 6 is green)

Produce what the user actually asked for:

• Program a board now: open_hardware_manager -> connect_hardware_server -> open_hardware_target -> program_device.
• Hand to embedded/Vitis (Zynq/MPSoC): export_hardware (include_bitstream=True) -> .xsa.
• Flash boot: generate_mcs / program_flash / add_flash_configuration.

---

Decision table — failed gate -> cause -> safe action -> owner

Failed gate	Likely cause	Smallest safe action	Hand off to
0 syntax/lint	Typo, latch, width/port mismatch, black box, compile order	Report violations; recommend RTL/file-order fix (do not waive)	lint skill
1 simulation	Functional RTL bug	Report failing TB checks via sim_get_report/sim_probe	simulation-debug skill
2 CDC (RTL)	Unsynchronized async crossing	Report check_cdc_lint findings; recommend synchronizer	cdc-analysis skill
3 synth error	Unsupported construct, missing file/param	get_synthesis_warnings, check_synthesis_issues; recommend RTL fix	synthesis-debug skill
3 CDC (netlist)	Crossing introduced/exposed by synthesis	Report report_cdc findings; recommend synchronizer	cdc-analysis skill
3 util overflow	Design too big for part	Report report_utilization; this is architectural, not a constraint	user (part/arch decision)
3 no clocks	Missing/empty XDC	Add real create_clock_constraint; never proceed with 0 clocks	user / constraints author
4 route fail / congestion	Routing/placement pressure	report_congestion; try ONE stronger impl strategy, else escalate	timing-closure skill
5 timing (WNS or WHS < 0)	Real setup or hold failure	extract_timing_metrics+analyze_critical_paths; constraints/strategy before RTL	timing-closure skill
5 route not 100%	Unrouted nets	report_route_status; congestion/strategy via timing-closure	timing-closure skill
5 DRC	Real rule violation (IO, config, etc.)	Report rule IDs from report_drc; fix root cause	user (confirm before any waiver)
5 methodology	Exception/CDC abuse	Report report_methodology; remove improper exceptions	cdc-analysis / timing-closure
6 bitstream write blocked	DRC regression at write	Report report_drc rule IDs; fix root cause (return to Stage 5)	user (confirm before any waiver)

---

Orchestration loop + STOP conditions

for stage in [0:static, 1:sim, 2:cdc, 3:synth, 4:impl, 5:signoff, 6:bitstream+reconfirm]:
    run stage
    pull FRESH evidence with the gate's tools
    if gate PASS:
        continue
    else:
        STOP. Do not advance. Hand the specific evidence to the owner skill.

Note the ordering: signoff (Stage 5) gates the implemented design before the bitstream is written (Stage 6). You never advance to generate_bitstream until setup AND hold timing, routing, DRC, and methodology are all green.

Hard STOP conditions (do not advance, do not retry blindly):

• Any gate fails on fresh tool output.
• A long async run shows STATUS = ERROR / aborted in get_run_status / sim_get_sim_status.
• You would have to silence a real violation (false_path / multicycle / waiver / disable_rule) to make a gate go green.
• You have tried one safe strategy/constraint change at a stage and it did not cross the gate — escalate, do not loop through strategy permutations.

Do not thrash: at most one safe remediation attempt per stage within this skill (e.g., default impl strategy missed timing -> try one Performance strategy). Beyond that, present options + costs and hand to the specialist. Constraint/strategy changes come before any RTL change, and RTL changes are recommended to the user, never silently applied.

---

Safety rails (do not violate)

1. Evidence before claims. "Bitstream is valid / timing met / DRC clean / CDC clean" requires fresh post-implementation tool output in THIS session (extract_timing_metrics, report_route_status, report_drc, report_methodology). A returned generate_bitstream or a green run_full_flow line is not proof of signoff. Synthesis numbers never prove signoff.
2. Signoff before bitstream. The post-route signoff gate (Stage 5) runs on the open implemented design before generate_bitstream. Never write a bitstream on an unverified design; never reorder these.
3. No fake-pass. Never apply set_false_path, set_multicycle_path, set_max_delay, waive_lint_violation, disable_lint_rule, or set_clock_groups to make a violation disappear. Exceptions are legal only when the path is genuinely exempt — state the assumption explicitly, and if the item could be real (a CDC, an actual long path), ask the user first.
4. Smallest safe change first. Constraints/strategy before RTL. Default strategy before exotic strategy. One change-class per iteration so the next measurement attributes cause to effect.
5. Never proceed on a vacuous pass. Zero constraint files / zero clocks / no testbench are NOT passes — they are missing verification. Call them out and get user direction.
6. Recommend RTL edits; do not silently rewrite the design. Use read_file/read_file_lines to cite the issue; propose the edit; let the user (or an explicit instruction) approve update_file/replace_in_file.
7. Long flows use async + poll. Synthesis, implementation, and long simulation go through *_async + get_run_status / sim_get_sim_status, never a blocking call that risks a timeout mid-build.
8. Real tools only. Use only the exact SynthPilot tool names. If a needed capability (e.g., explicit checkpoint export, or automated incremental compile) is not in the catalog, say so rather than inventing a tool. Vivado runs persist their own state on disk, and open_synthesized_design / open_implemented_design reopen a run for analysis — you do not need (and must not invent) a separate checkpoint-write tool.
9. Surface trade-offs then stop. When safe options are exhausted, present the options and their costs (area/power/effort/risk) and hand back to the human.

---

Output format

Report the flow as a gate table, then a verdict. Show before/after where a remediation was attempted.

=== FULL-FLOW DEMO — <project> @ <part>, top=<top> ===

Prereqs:  connection OK | project OK | top OK | constraints=<N clocks> | tier=<...>

Stage gates (fresh evidence):
  [PASS] 0 Static     syntax clean; lint: 0 err / <w> warn
  [PASS] 1 Sim        TB PASS (<runtime>, self-checking)
  [PASS] 2 CDC (RTL)  0 critical crossings (check_cdc_lint)
  [PASS] 3 Synth      COMPLETE; clocks=<list>; util fits (LUT x%/FF y%); report_cdc 0 critical
  [PASS] 4 Impl       route_design COMPLETE
  [PASS] 5 SIGNOFF    WNS=<+ns> AND WHS=<+ns> (all clocks) | 100% routed | DRC 0 err | methodology clean
  [PASS] 6 Bitstream  written -> <path/to.bit>; re-confirm: 100% routed, DRC 0 err
Artifacts:   <.bit> [, <.xsa> / <.mcs> / programmed device]

VERDICT: PASS — signoff gate (Stage 5) met on fresh post-route evidence; bitstream written and re-confirmed.
         (or) STOPPED at Stage <n>: <one-line failure> -> handed to <skill> with <evidence>.

Rules for the report:

• Every [PASS] must cite the tool that proved it; an unproven stage is [UNVERIFIED], never [PASS].
• The final VERDICT: PASS is permitted only when Gate 5 is green — setup (WNS ≥ 0 / TNS = 0) and hold (WHS ≥ 0 / THS = 0) across all clocks, 100% routed, DRC 0 errors, methodology clean — on fresh extract_timing_metrics + report_route_status + report_drc + report_methodology output, and Gate 6 confirms the bitstream was written with signoff still holding. Otherwise report exactly which gate stopped the flow and which specialist skill now owns it.