Timing Analysis

Running the STA Shell

The STA shell is an interactive TCL REPL. Do not launch the STA shell as a background process. Always pipe commands non-interactively:

echo '<tcl commands>; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

Evidence Log

Before reading files, running commands, or editing constraints, create or update .cache/ai/timing-analysis.md:

touch .cache/ai/timing-analysis.md

Keep a running log for the entire task. After every step, append:

• The action you took
• The evidence you gathered (file path and line numbers, exact command, report excerpt, or RTL/SDC snippet)
• The observation or inference supported by that evidence
• The decision you made (or the next question to answer)

Every constraint recommendation, SDC edit, and timing-closure conclusion must be evidence based. If the log does not contain evidence that justifies a decision, do not make that decision yet. Gather more evidence first and record it in the log.

Workflow

1. Gather Context (parallel reads and log the evidence)

Read these files in parallel before doing anything else. All are required to make correct constraint decisions:

1. ./reference/design.md - clocks, components, timing parameters, bus arbitration, signal mapping
2. gw/EconoPET/EconoPET.sdc - current constraints
3. build/gw/outflow/EconoPET.pt.sdc - constraint template (port/clock completeness checklist)

Record in .cache/ai/timing-analysis.md what each file says that is relevant to the current issue. Cite exact paths, line numbers, clocks, ports, and timing assumptions.

2. Assess Current State and log the findings

Run check_timing first. It is the single most informative command, reporting exactly how many ports are unconstrained:

echo 'check_timing; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

Add -verbose to list every violating pin. The output table shows:

Target: 0 unconstrained inputs and 0 unconstrained outputs. Ports with set_false_path count as "constrained" (reported separately in the output).

Then run timing summary and the worst setup/hold paths:

echo 'report_timing_summary; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

echo 'report_timing -from_clock sys_clock_i -to_clock sys_clock_i -setup; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

echo 'report_timing -from_clock sys_clock_i -to_clock sys_clock_i -hold; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

If you need more than one path, use -npaths and optionally -nworst:

echo 'report_timing -from_clock sys_clock_i -to_clock sys_clock_i -setup -npaths 10 -nworst 1; exit' \
  | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

To check CDC paths between clock domains:

echo 'report_cdc -details; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

To list all post-synthesis ports (ports optimized away by synthesis are removed):

echo 'puts "INPUTS:"; puts [all_inputs]; puts "OUTPUTS:"; puts [all_outputs]; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

Log each command, the important output, and what it proves. Note: Efinity does not support -max_paths. Use -npaths / -nworst instead.

3. Classify Ports for Constraint Assignment

Every port in the post-synthesis netlist needs a constraint. Read the RTL (gw/EconoPET/src/top.sv, main.sv, and relevant submodules) to classify each port. This step is critical -- the constraint type depends on the signal driver. Record the RTL evidence for each classification decision in the log.

Output Port Classification

Input Port Classification

Efinix Tristate OE Signals

Efinix FPGAs split tristate I/O into _o (data), _oe (output enable), and _i (input) ports. OE signals frequently have long combinational paths through address decoding gated by cpu_be_o. Because the bus arbiter toggles BE multiple sys_clock_i cycles before data transitions, OE changes have a multi-cycle budget. Use set_false_path -to [get_ports {*_oe[*]}] for these.

Trap: Constraining OE signals with set_output_delay causes setup violations on paths like cpu_be_o -> address_decode -> cpu_addr_oe[*] because the combinational depth exceeds one sys_clock_i period. This does not indicate a real timing problem.

Do not generalize this to all synchronous outputs. Prefer set_multicycle_path for genuinely synchronous multi-cycle behavior. Use set_false_path only when the path should not be analyzed at all.

4. Cross-Reference with the Constraint Template

Read build/gw/outflow/EconoPET.pt.sdc. It is regenerated each time the gateware is compiled and contains a commented-out set_input_delay or set_output_delay stub for every port/clock pair that the Interface Designer expects to be constrained. It also contains create_clock statements for PLL and pad-entry clocks.

Use it as a checklist:

• Verify that every create_clock in the template has a corresponding definition (or an intentional omission with a comment) in the project SDC.
• Verify that every port listed in the template is covered by a set_input_delay, set_output_delay, or set_false_path in the project SDC. Unconstrained ports are left with default timing and may cause silent failures.
• Watch for new ports that appear after Interface Designer changes (they show up in the template but may be missing from the project SDC).
• Ports that synthesis optimizes away will not appear in the post-synthesis netlist, but keeping constraints for them in the SDC is harmless.

5. Edit the SDC File

Edit gw/EconoPET/EconoPET.sdc. After editing, you can re-read the SDC to check for syntax errors and re-analyze timing against the existing netlist:

echo 'reset_timing; delete_timing_results; read_sdc; report_timing_summary; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

This validates the constraints parse correctly and gives a first look at timing impact, but the netlist has not been re-optimized for the new constraints. Setup violations against the old netlist may resolve after a full rebuild (step 6).

Before each SDC edit, write the proposed change in the log, cite the supporting evidence, and explain why the chosen constraint is the correct model. If you reject an alternative (set_false_path, set_multicycle_path, different clock, etc.), record why.

If a setup violation appears on an output path that was previously unconstrained, check whether the path has a multi-cycle budget. If so, use set_false_path instead of set_output_delay.

6. Rebuild and Verify

Constraint changes that affect which paths are optimized (adding/removing output delays, false paths, clock definitions) require a full rebuild so that synthesis and place-and-route can optimize for the new constraints:

cmake --build --preset gw

After the rebuild completes, re-run the STA shell to confirm timing is clean:

echo 'report_timing_summary; exit' \
    | .github/skills/timing-analysis/scripts/sta-repl.sh 2>&1

Then run check_timing again to verify 0 unconstrained ports remain. Append the final verification results, residual risks, and the final decision summary to .cache/ai/timing-analysis.md.

SDC Conventions

Constraint Order

Order constraints exactly as follows (dependencies require this sequence):

1. Primary clocks (create_clock)
2. Virtual clocks (create_clock without a target)
3. Generated clocks (create_generated_clock)
4. Clock groups (set_clock_groups)
5. Input and output delays (set_input_delay, set_output_delay)
6. Timing exceptions in this order: a. False paths (set_false_path) b. Max/min delays (set_max_delay, set_min_delay) c. Multicycle paths (set_multicycle_path)

Always define a clock before referencing it in any I/O delay or exception constraint. A constraint referencing an undefined clock is silently ignored.

Exception Priority

When the same path has multiple exceptions, Efinity applies them in this order (highest priority first):

1. set_clock_groups
2. set_false_path
3. set_max_delay / set_min_delay
4. set_multicycle_path

SDC Syntax Rules

• SDC is case sensitive. Use lowercase net names (synthesis converts all names to lowercase).
• # starts a comment.
• \ at end of line continues the command on the next line.
• * is a wildcard (e.g., Oled* matches Oled0, Oled_en).
• Use get_ports, get_pins, get_cells, get_nets object specifiers. The pipe | separates instance name from port name (e.g., FF1|Q).
• Perl regex is available with -regexp option on object specifiers. Escape brackets when using regex.

Virtual Clocks and Real Clocks

Use a virtual clock as the set_input_delay/set_output_delay reference when the board clock is off-chip. This removes interface clock latency and uncertainty from I/O constraints. Put the virtual clock and core clock in the same clock group so the timer analyzes transfers between them.

Use a real pad clock when the relationship is to the FPGA pad clock. Use -reference_pin for synchronized or forwarded-clock interfaces.

Input and Output Delay Values

Default rule:

1. If the interface is synchronized by Interface Designer, copy the set_input_delay / set_output_delay constraints from <project>.pt.sdc. Keep -reference_pin when present.
2. If the interface is not synchronized (bypass mode), calculate delays from the external device timing, board delay, and GPIO timing values in <project>.pt_timing.rpt.
3. Only use simplified board-delay-only constraints when the design's RTL and protocol prove that ordinary edge-based STA is not the right model.

Delay Equations

Synchronized I/O (copy from <project>.pt.sdc):

Negative minimum output delay is valid. Do not clamp to zero.

Unsynchronized I/O (bypass mode, receive clock):

For forward-clock I/O, add -reference_pin and include GPIO_CLK_OUT. See the Efinity Timing Closure User Guide for the four forward-clock modes. GPIO_CLK_IN delay is in set_clock_latency, not in I/O delay constraints.

EconoPET-Specific Exception

Some CPU-bus-facing signals use false paths or simplified delays because the bus arbiter in timing.sv creates a protocol-level multi-cycle budget. Justify from ./reference/design.md and RTL, not as a general rule.

Clock Definitions

Match the template form with explicit -name and [get_ports]:

create_clock -period $period -name sys_clock_i [get_ports {sys_clock_i}]

Common mistake: using -name without a target creates a virtual clock. That is correct only when you intentionally want an off-chip reference clock. Efinity prints an info message when it finds a virtual clock definition.

Use -add to define multiple clocks on the same target (e.g., dynamic clock muxes). Without -add, a later create_clock on the same target overwrites the previous one.

set_clock_groups

# Explicit all-groups form (preferred for this project)
set_clock_groups -asynchronous -group {sys_clock_i} -group {spi0_sck_i}

# Single-group form: cuts this group to all other clocks
set_clock_groups -asynchronous -group {spi0_sck_i}

Default (no flag) is -exclusive. Use -asynchronous for independent clock sources. Use -exclusive for clocks that never operate simultaneously (e.g., dynamic mux). Prefer the all-groups form: it documents known relationships and requires explicit updates when adding clocks.

Multicycle Paths

Default single-cycle: setup = 1, hold = 0. To shift by N cycles with width M: setup = N, hold = M - 1.

For different clock frequencies, use -start/-end to select the reference:

• Launch faster than capture: -start for setup (hold defaults to -start)
• Launch slower than capture: -end for hold (setup defaults to -end)

Do not use both -start and -end on the same constraint.

Common Fix Patterns

Setup Violations

Hold Violations

Hold Slack on Internal Paths

Internal register-to-register hold failures are P&R placement issues, not SDC problems. Options: seed sweep, set_min_delay (sparingly), or pipeline register.

Warning: set_min_delay and set_max_delay override clock-derived timing. They can mask real violations -- the software honors your input without error, but the issue appears on the board. Avoid unless no alternative exists.

Common SDC Mistakes

Timing Closure Strategies

When constraints are correct but timing still fails, try these approaches in