# Equivalence Check

> Run Logic Equivalence Checking (LEC) between two representations of a design — RTL vs gate-level netlist, pre-ECO vs post-ECO, or golden vs revised RTL — to prove functional identity. Use when the user says "LEC", "equivalence check", "formal equivalence", "is this netlist equivalent", "post-ECO check".

- Skill: `vibeic/equivalence-check` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add vibeic/equivalence-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vibeic/equivalence-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vibeic (https://skillmd.com/u/vibeic)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/vibeic/equivalence-check

---


# Equivalence Check (LEC)

## Captured rule — hierarchy staging and the native proof verdict

A hard-macro staged on only ONE side makes `hierarchy -check` abort with
`compared_points: 0`, which must NOT be booked as a real FAIL. Stage the
required hierarchy on both sides before claiming a logical comparison.
An unexecuted comparison remains `NOT_MEASURED`.

A step must not report PASS over a report whose json verdict is FAIL.
Read the native proof report, not only the enclosing process exit code.

> **Doctrine (v0.1.50):** 把修法寫進工具，而非寫進 prompt.
> Programs first; AI is the backstop. Never claim PASS without the tool's verdict.

After every transformation that touches the netlist — synthesis, DFT
insertion, clock gating, ECO — someone has to prove the result is
functionally identical to the golden RTL. This skill drives that check
through MCP-EDA's `eda_lvs` `yosys_equiv` mode.

## Mandatory Deterministic Preflight

```bash
# MCP tool call (handles SAT-engine corner cases since v0.1.12):
eda_lvs({
  mode: "yosys_equiv",
  layout_netlist: "<post-transformation-netlist>.v",
  schematic_netlist: "<golden-netlist>.v",
  top_module: "<top>",
  pdk: "sky130",  // or "gf180" or "custom" with custom_lib
})
```

The tool returns `equiv_cells_total / proven / unproven` plus
`sat_model_unsupported_cells[]` (for custom-PDK Liberty primitives
without built-in SAT models), and writes the result to `reports/lec.json`
(+ optional `reports/lec.rpt`).

Run the selected native equivalence tool and read its compared-point count, unmatched points and proven/unproven status. An empty or incomplete comparison is NOT_MEASURED, not equivalence.

Use the native verdict and complete proof population. Keep the enclosing
runner's exit status separate: another unmeasured row can make that runner
exit nonzero while the native equivalence row passes.

## Captured rule

Read a hardened child's own netlist on both sides of its parent's proof,
with the parameters that were applied during hardening. Physical-only taps,
fill and end caps inside that netlist need empty module definitions when
their LEF class declares that role and no functional model exists. After
flattening, delete their instances and the empty modules before partitioning.
Yosys requires `delete =<module>` to select an empty module; supplying only
the definition leaves EQY unable to match it. The retained hierarchical run
proved all 9,199 partitions, including 65 gold-X partitions, with zero
unproved against the original zero limit. Native LVS still judges physical
connectivity. Unmeasured child simulation or power remains unmeasured.

## When to use

- Post-synthesis (RTL ↔ synth netlist)
- Post-DFT (pre-DFT ↔ post-DFT netlist, with test pins held at functional values)
- Post-ECO (pre-ECO netlist ↔ post-ECO netlist)
- Post-hand-edit (sanity check RTL refactor)

## Inputs

1. Golden (reference) design
2. Revised design
3. Key-point mapping hints (register name correspondence) if names changed
4. Constraints: which pins are test-mode, which are scan-enable, etc.
5. Tool: Yosys `equiv_*` commands (open), Synopsys Formality, Cadence Conformal

## Workflow

1. **Compile both sides** into a common internal representation
2. **Map key points**: registers, primary I/O, black-box boundaries
3. **Report unmapped points** — usually where the bug is
4. **Run verification** — prove cone-of-logic equivalence per key point
5. **Triage mismatches**:
   - Real functional change → flag to user
   - Reset-state difference → may be benign if documented
   - Uninitialized X-propagation → investigate

## Output format

- `lec/<design>_lec.tcl` (Yosys / Formality script)
- `lec/<design>_report.md`:
  - Mapped / unmapped point count
  - Status per key point
  - Debug pointers for every mismatch

## Tool prerequisites

Open flow: Yosys with `equiv_make` / `equiv_simple` / `equiv_induct`. Commercial: Formality, Conformal. The skill produces the script; execution requires the tool.

## Technical basis

Cone-of-logic equivalence checking with SAT / BDD back-ends is the industry standard for post-synthesis sign-off. Yosys implements this via the `equiv_*` pass family (https://yosyshq.readthedocs.io/).

## Handoff

- Mismatch → `/rtl-repair` or `/eco-plan`
- Re-run after fix → re-invoke this skill

## Captured rule — size EQY scratch before launching a CPU-class design

EQY partitions a CPU-class design into many small proofs, and each one keeps its
own copy of the work. Measured on Ibex chip runs (2026-11-07): 198 GB and
168 GB of partition files in two runs on one host, and 768 GB in one run on
another, against 400 GB planned. A full disk stops every job on that host, and
the later copy-back error hides the cause. Before launching, check free space
with `df` on the run directory itself, which is often a data disk, not `/`, and
plan about 800 GB for an Ibex-class chip.

## Captured rule — retain native FSM state correspondence

Enable the existing native `SYNTH_FSM_ENCFILE` report by default while honoring
explicit project overrides. Use only the report of the netlist's own producer:
the file beside the netlist, or, for a later netlist of the same step tree
(placed, routed, final adopted), the one report written by that tree's
synthesis row. Never borrow a mapping from another candidate or project.
Without it the final adopted proof silently falls back to hidden state names
and whole-core partitions: on SHA256 IP (2026-11-12) the same design proved in
87 partitions and 81 s after synthesis but 49 partitions and 4,916 s at the
final step, with 12 to 15 GB per candidate. When a later equivalence row is far
slower than the synthesis one, compare the two generated `equivalence.eqy`
files first.
The EQY path uses that report to select native Gold FSM normalization, then
splits the normalized state wires so the producer's emitted scalar names can
match. Each correspondence remains a native proof obligation. Keep the
separate `equiv_make -encfile` whole-word translation recipe intact; do not
hand-supply state encodings or assume that state names establish equality.

On the IC route, Gold FSM processing can run in native `gold_pads.ys` before
the final EQY configuration reads the prepared core. Inspect those native
events and matched IDs when diagnosing activation; absence of `fsm` from the
final EQY script alone does not establish missing preparation. Retain every
module output, reset replay, initial-state and Gold-X behavior, and read all
native partition results against the original zero-unproved limit.

## Captured rule

### Normalize instantiated ICGs before the native clock-edge model

A reset-aware gated implementation cannot be compared as if each surviving
clock were the same implicit single SAT edge. Detect **instantiated** ICG
masters from their existing synthesis Liberty clock-input/output pin roles;
when present, select native Yosys `clk2fflogic` instead of `async2sync` in the
shared EQY preparation. First run native `formalff -declockgate` and
`opt_clean`: supported gating patterns become root-clock enable FFs, avoiding
shared clock-history state that couples otherwise separate data banks.
Unsupported patterns remain for the existing edge model. Keep the reset
replay, operands, every module output, decoded-state safety guard, assertion,
strategy depth, timeout and original zero-unproved limit intact. An unused
ICG or an ordinary clock-marked buffer must not select the ICG clock model.
Never edit produced gate-netlist operands or waive a failing proof obligation.

Program capture: `flow_native_verification.eqy_clock_gates` uses the existing
Liberty pin-role reader (including compressed libraries), and `eqy` records
the selected native clock model and actual ICG masters. cpu_queue
`sha256-eqy-native-edge-model0476-oai`, image 0.4.76, replays unchanged SHA256
operands: **288 disproved partitions -> 0 unproved**, **all 1623 partitions
PASS including 59 gold-X partitions**, native wrapper comparison **0
mismatches**; **451.735 s** native tools. Native `eqy` still decides every
partition and still owns the verdict.

`sha256-eqy-clockmodel-negative-control0476-oai`: **4/4 PASS**, including an
edge-mode positive proof and an intentionally wrong data function that must
produce native **FAIL**, not merely a checker/tool error. Matched existing
regressions: **389 PASS / 6 pre-existing FAIL** at both base and repair; all six
are unrelated formal-source-path expectation cases, not suppressed or changed.
The combined repair run is **393 PASS / the same 6 FAIL**. `NEW_FAILED=[]` in
the measured regression population. This repairs the gated candidate's native
LEC row, not its residual power budget or full-chip physical signoff. Do not
adopt a gated physical point merely because this equivalence step passes.

## Captured rule

### Keep native EQY partitions and the stock strategy list

The shared synthesis and final adopted-netlist comparisons use EQY's native
matched fragments. Global `group *` joins independent state obligations into a
whole-design proof. Blanket `amend *` adds Gold logic to consumer partitions.
In the grouped AES IP comparison, one partition had 133875 Gate cells. SAT
reached its five-step induction bound, and unbounded ABC PDR ran for more than
34 hours.

Keep every output and state obligation and the original operands. Use stock
LibreLane's strategies in order: SAT depth 5, SBY `abc pdr -rfi`, then SBY
`smtbmc bitwuzla` depth 2. Keep the existing scoped pad-boundary rules when
preparing a pad-free core and the alias and decoded-state handling in EQY.

When the tool groups unrelated outputs of a wide inversion or mux, run
`simplemap t:$not t:$mux` after selecting the observable names and before
matching. These cells produce each output bit independently, with one shared
selector for the mux. Scalarizing them keeps the named signals and the original
comparison obligations. Leave flip-flop words intact.

A failed partition trace supplies cut inputs, often without the full design's
primary inputs. Use native reachability to complete or refute the cut history
on each original operand from reset. Replay a found primary-input witness
with native simulation. An infeasible history explains a false partition
failure; the enclosing equivalence proof still has to run.

Use the native partition input and output bit maps to find each failed
partition's direct input producers. Add exact EQY `merge` rules for those
producers and run EQY again. The merged partition still asserts every original
output bit. Keep the earlier failed traces. Stop growing the cone when there
are no producer edges or the partition graph does not shrink. An actual
changed function still has to fail.

The native checker still owns each partition result. A strategy timeout or
unknown result cannot satisfy the original zero-unproved limit. A bounded
replay may set EQY's native per-strategy timeout without changing the shipped
stock defaults. Report every failed partition with its native trace and keep
undecided rows `NOT_MEASURED`.

The regression exercises independent matched state cones through the shared
adapter with and without pads. The grouped IP comparison failed with one
partition, while its two pad cases passed. The repaired comparison must retain
multiple native partitions and still detect the changed-function case.

Image 0.4.76 evidence from `aes-ip-eqy-native-partitions-consumers-i0476-oai`
has 208 matching native tests passing after repair, with no new failed IDs.
AES has 109 proved, 64 failed with traces, and one undecided partition. Both
Subservient IP comparisons have 105 proved and 49 failed partitions. One
Subservient trace assigns 0 and 1 to two cuts of the same original Gold bit,
directly exposing the alias defect addressed by eqy#5. The other failures
remain unclassified. Both SPM IP comparisons retain PASS with two partitions
each in `aes-ip-eqy-native-partitions-spm-i0476-oai`. These bounded replays
use a native 60-second strategy timeout. Image 0.4.76 also lacks the Bitwuzla
executable, leaving the AES undecided cone without that backend's result.
Land only on an image with eqy#5 and recheck the regressed consumers there.

The original-operand recheck on image 0.4.77, with eqy#5 present, is
`aes-ip-eqy-native-consumers-v14093-i0477-oai`. All 208 head tests pass with
no new failed IDs. Both SPM comparisons still prove both partitions. AES
reports 92 proved and 17 failed partitions. Both Subservient comparisons
report 41 proved and 23 failed partitions. Every failed partition has a
native trace; none of these consumer results is undecided. The partition
populations changed with the native tool, so counts across images are not
matched-point deltas.

In that recheck, Subservient still regressed from its grouped PASS baseline.
All 23 original failed histories per Subservient row, and all 17 original AES
histories, were then refuted on both full reset-initialized operands. None
reproduced an internal difference from reset. These are classifications of the
retained histories, not unbounded reachability results.

The scoped producer merges proved 26 of 26 partitions in both Subservient
comparisons, with all 263 compared bits retained. Both SPM comparisons stayed
at 2 of 2 with the same 64 bits. The packed-inversion regression keeps the two
independent output words separate, checks all 18 bits, and retains native FAIL
for a changed function. The matched panel has 414 passing tests and no new
failed IDs. AES retains all 2236 compared bits; EQY proved 22 partitions and
left `chip_top.idle_o` unproved. SAT and PDR reached the diagnostic timeouts,
and the image lacked Bitwuzla, so EQY exited with an error. This result does
not meet the original limit.

### Retain native SMT validation of ABC counterexamples

Set EQY's supported `option aigsmt bitwuzla` on the ABC PDR strategy. Yices ran
out of memory while loading a retained word model for counterexample replay. Bitwuzla
replayed the same model and witness and returned a validated FAILED result.
Keep the assertions, assumptions and native witness validation unchanged.
A validated partition counterexample still needs classification.
This repairs witness replay only; the complete row still requires zero
unproved obligations.

