shinei-nouzen-arch/fpga-agent/vivado-timing-closure

Vivado Timing Closure & Optimization

Systematic FPGA timing convergence based on AMD UltraFast Design Methodology (UG949) and the XTP301 checklist, combined with practical optimization experience.

For explanation or report-only requests, analyze the available evidence and identify any missing verification without requiring a new build. Run optimization only when it is within the user's request, and reuse valid results for the current design. Existing authorization covers necessary in-scope follow-up; changing a strategy or consulting vivado-tcl does not require repeated confirmation. Preserve explicit limits on RTL, netlist, interfaces, constraints, target frequency, runtime, and hardware operations.

Quick Decision Flow

Inspect current reports / open the relevant checkpoint when execution is in scope
  → Validate the existing constraint baseline and record all timing metrics
  → WNS >= 0 or high QoR score? → Full final acceptance checks
                                  → All checks and requested deliverables complete? → DONE
                                  → Otherwise: investigate the remaining gaps
  → Timing still failing? → Diagnose constraints, paths, congestion, and QoR
                           → Apply an evidence-backed, authorized strategy
                           → Compare results; preserve the best candidate
                           → Plateau? End this strategy's loop and reassess

Timing Acceptance Criteria

For a timing-closure task, apply these checks to the same final design with the full intended constraints, including I/O timing. Verify zero unconstrained internal endpoints, intended exception coverage, and applicable CDC, DRC, and methodology findings. Run report_bus_skew separately when bus-skew constraints exist. Resolve findings or use justified waivers only within the task's authorization; do not weaken constraints to produce a pass.

WNS >= 0 or a high QoR score starts final verification; neither is a completion condition. Keep the positive-margin requirements above unless the user has explicitly specified a different acceptance policy. Missing metrics or checks remain unverified, not passed. Timing closure is complete only after the applicable checks pass and the requested artifacts and validation results are delivered; bitstream generation or hardware programming is not an automatic next stage.

Important: Fmax is NOT explicitly shown in Vivado reports. Always calculate it: Fmax = 1000 / (period - WNS) where WNS is the value from the timing summary (negative means failing).

Layer 1: Constraint Validation (ALWAYS START HERE)

Before any optimization, verify the design is properly constrained. Skipping this wastes hours optimizing paths that aren't the real problem.

Essential checks (in priority order):

report_timing_summary          → WNS/TNS/WHS/THS/WPWS baseline
check_timing                   → Unconstrained paths (internal endpoints MUST be 0)
report_clock_interaction       → Clock relationships, identify unsynchronized crossings
report_methodology             → TIMING + XDC rule violations
report_qor_assessment          → Overall design health score (1-5)

Interpreting QoR Assessment:

• Score 1-2: Major constraint or methodology issues — fix these first
• Score 3: Design has timing challenges but constraints are reasonable
• Score 4-5: Good design quality, remaining issues are fine-grained

Read references/methodology-checklist.md for specific DRC checks mapped from XTP301.

Layer 2: Tool-Managed Implementation Optimization (May Change the Netlist)

This is where the biggest gains come from. The directives below are ordered by typical impact.

Built-in physical optimization can replicate cells, restructure logic, or move registers even when RTL source is unchanged. Honor explicit restrictions on netlist changes; this layer does not exempt tool-managed changes from those restrictions. Preserve a baseline checkpoint and compare the candidate's timing, resources, and applicable functional checks.

The Golden Sequence (proven 20-45% Fmax improvement):

# Step 1: Re-place with exploration (the single biggest lever)
place_design -directive Explore
 
# Step 2: Physical optimization after placement
phys_opt_design -directive Explore
 
# Step 3: Route with timing effort
route_design
 
# Step 4: Check and iterate if needed
report_timing_summary
 
# Step 5: Aggressive follow-up (if still failing)
phys_opt_design -directive AggressiveExplore
route_design -directive NoTimingRelaxation -tns_cleanup

Directive Reference:

Iteration Pattern:

After each applicable phys_opt/routing cycle, compare WNS, TNS, failing endpoints, hold, pulse width, route status, and any stated resource limits on a consistent constraint baseline. TNS or endpoint improvements can be meaningful progress even when WNS is unchanged. Preserve the best candidate, including candidates that would otherwise be lost to a later regression.

• If WNS >= 0, run the full Timing Acceptance Criteria above and investigate any remaining failures or missing checks.
• End the current strategy's repeated loop after 3 consecutive rounds without material progress, or when WNS improvement per round is < 0.005 ns with no meaningful progress in the other relevant metrics.
• At a plateau, re-examine the limiting paths and continue another evidence-backed strategy within the existing scope and overall attempt, runtime, and resource limits. Do not request confirmation merely to switch an already-authorized strategy.
• If no feasible in-scope next step remains, or an overall limit is reached, report that closure is incomplete, retain the best result, and identify the remaining violations and concrete constraint or missing decision. Do not treat a plateau as success or restart the search indefinitely.

Stage rule: Post-place phys_opt_design can run after placement. Post-route optimization requires the appropriate routed design state. Check the actual design state and tool requirements; do not impose the post-route prerequisite on post-place optimization. See vivado-impl for stage-specific options.

Using ML Strategy Suggestions:

report_qor_suggestions

Outputs RQS_STRAT strategies recommended by Vivado's ML analysis. The top 3 strategies are auto-generated for your specific design. Each includes specific directives for opt_design/place_design/phys_opt_design/route_design.

Layer 3: Pblock Area Constraints

Use when critical-path analysis shows substantial physical spread; Manhattan distance > 70 tiles on 5+ critical paths is a heuristic, not a required output from a specific helper.

Pblock Flow:

1. Use report_design_analysis, get_timing_paths, and cell placement properties to inspect critical-path spread and select the affected logic.
2. Use report_utilization for that logic and inspect device sites/clock regions to size a region with resource headroom.
3. If available, the environment-specific helpers analyze_critical_path_spread, report_utilization_for_pblock, analyze_fabric_for_pblock, and convert_fabric_region_to_pblock can assist. They are not built-in Vivado commands and their implementations are not included here; inspect the available tool or script interface before use. Check whether a helper already includes sizing headroom.
4. Without those helpers or RapidWright, use the native reports, object queries, and manual sizing guidance below. An unavailable optional tool does not block the rest of the task or authorize its installation. If a particular result cannot be verified, state that limitation and continue unaffected work.

Apply the chosen constraint to the selected logic in a candidate design and compare it with the baseline. Adapt the following Non-Project Mode example to the current flow:

# Use observed target cells and device ranges; evaluate on a candidate copy.
place_design -unplace
create_pblock pblock_opt
add_cells_to_pblock pblock_opt [get_cells <target_cell_patterns>]
resize_pblock pblock_opt -add <RANGES>
set_property IS_SOFT false [get_pblocks pblock_opt]
place_design
phys_opt_design -directive Explore
route_design

Rules of thumb for manual pblock sizing:

• Compute centroid of critical path cells (average X/Y coordinates)
• Size region to ~2x the needed SLICE count (aim for 50% utilization)
• Expand to cover the critical cell bounding box + 20% margin
• Clamp to device SLICE bounds (xcvu3p: X[0:168], Y[0:299])
• Avoid expanding to entire chip — that negates the constraint effect

Layer 4: Netlist-Level Optimization (Use with Caution)

Only proceed when physical optimization (Layers 2-3) is exhausted. These modify the netlist and can degrade timing if misapplied.

Evaluate the applicable physical strategies; lack of an optional helper alone is not evidence that those strategies are exhausted. The RapidWright calls below are examples of optional helper interfaces, not guaranteed package APIs. Use them only when an installed tool exposes the operation. Prefer available Vivado capabilities for equivalent work when suitable, and preserve explicit limits on netlist editing.

Always test manual netlist changes on a copy first. Use a tool's documented dry-run or --test option only if that tool supports it. Otherwise perform appropriate structural/functional validation on the candidate and re-check routing, timing, and resources. Do not adopt an unverified candidate merely because a specific test option is unavailable; report that limitation while continuing other feasible work.

Fanout Splitting:

When fanout > 100 on critical path nets:

# In RapidWright:
optimize_fanout(net_name="<net>", split_factor=<3-8>)
# split_factor: fanout/100, min 3, max 8

Warning: Fanout splitting replicates source drivers, adding cells. This can cause placement congestion. On designs with inherently high fanout architecture (e.g., neural network accelerators), it may degrade WNS by 0.5+ ns. Always compare before/after.

LUT Input Cone Merging:

When paths have chains of small LUTs (LUT2-LUT5 feeding each other):

# Find candidate pins: iterate nets where source cell is a LUT
# and sink cell is also a LUT
optimize_lut_input_cone(hierarchical_pin_names=[
    "cell_name/A1",  # Format: hierarchical_cell_name/pin_name
    ...
])

Pre-check: Count LUT types. If LUT6 dominates (>80%) with few LUT2-LUT5, merging has no targets and won't help.

Cell Re-placement (ECO):

When report_qor_suggestions shows route delay > 60% on specific paths:

# In RapidWright:
# 1. Read DCP
# 2. Identify cells on worst paths
# 3. Unplace target cells
# 4. Place at centroid of their connected cells
# 5. Write DCP
# 6. In Vivado: route_design only (keep placement)

Congestion Analysis & Resolution