Synth Doctor — EDA Error Classifier + Auto-Fix
Automatically diagnose EDA tool failures and provide actionable fix suggestions.
Read the native tool failure
Open the actual Yosys, OpenROAD or LibreLane log and identify the failed native command, design scope and diagnostic. Use the following patterns as repair ideas, not automatic verdicts or a confidence score. Verify the cause in the actual design before changing it.
Yosys diagnostic patterns
| Pattern | Frequency | Auto-fixable |
|---|---|---|
| UNPACKED_ARRAY | Common | Yes — flatten to packed |
| MULTI_DRIVER | Common | Yes — merge to single always_ff |
| RETURN_IN_FUNC | Occasional | Yes — use func name assignment |
| PAST_IN_COMB | Occasional | Yes — shadow register |
| AUTOMATIC_IN_FF | Occasional | Yes — module-level wire |
| LATCH_INFERENCE | Common | Yes — add default assignments |
| SYNTAX_ERROR | Varies | Manual review needed |
| MODULE_NOT_FOUND | Rare | Yes — add source file |
| WIDTH_MISMATCH | Common | Yes — explicit sizing |
| UNKNOWN | Rare | Manual review needed |
For multiple drivers, choose the merge priority from the actual FSM behavior. For width mismatches, select zero/sign extension from the signal semantics. An unrecognized error requires the raw native diagnostic and design context.
OpenROAD diagnostic patterns
| Pattern | OpenROAD signature | Canonical fix | conf |
|---|---|---|---|
| GPL_DIVERGE | GPL-*, "placement diverged" | skip (trivial design) | 0.50 |
| DRT_POWER_NET | POWER/GROUND net in signal router | global/PDN route only (manual) | 0.0 |
| FLOORPLAN_FAIL | IFP-*, die-area invalid | fix site name from cell LEF | 1.0 |
| DRC_SPACING | spacing/short violation | reduce utilization | 0.70 |
| TIMING_FAIL | negative slack / WNS<0 | re-arch long path / relax per spec | 0.0 |
| NO_CLOCK | "no clocks defined" | add (virtual) clock in SDC | 0.90 |
| CONGESTION | congestion / overflow | reduce density | 0.70 |
| DRT_ZERO_NET | DRT-0305 zero_ GROUND | tie-cell pass (setundef -zero; hilomap; splitnets; clean) | 1.0 |
| SITE_NOT_FOUND | IFP-0018 site not found | read SITE from cell LEF | 1.0 |
| MISSING_TRACKS | PPL-0021 no routing tracks | add make_tracks from LEF PITCH | 0.90 |
Do not silently relax a fixed clock requirement to repair timing. Read the actual critical path and choose a physical or architectural fix. Resolve power-grid, floorplan and routing issues in the design, configuration or tool.
arith_ss_corner_risk_check.py — slow-corner timing-risk predictor (pre-synth)
A TIMING_FAIL at the SS (slow-slow, cold, low-V) corner is most often a
wide, single-cycle ripple-carry add / accumulate / compare chain. The spm
and sha256 benchmark ICs both closed at TT but failed cold SS, and were rebuilt
with carry-save / carry-select / CSA-tree architectures. Run this before
synth to localise the risk, and again when triaging a TIMING_FAIL instead of
guessing which path to pipeline:
python3 programs/arith_ss_corner_risk_check.py --rtl-dir <rtl> # advisory
python3 programs/arith_ss_corner_risk_check.py --strict --rtl-dir <rtl> # exit 1 on HIGH
HIGH findings name the destination register, the carry-chain width, and the add-chain depth. The fix is a carry-save / carry-select / parallel-prefix adder or a pipeline stage — not a clock-period relax when the spec clock is fixed. Designs that document a carry-save / carry-select / prefix / pipelined strategy (in module name, signal names, or comments) are recognised and not flagged.
Map a prefix adder with native Yosys commands
Use Yosys's available carry-lookahead maps when the measured carry chain is
actually limiting timing. For a non-default topology, apply the selected map
and +/techmap.v in the same techmap call with the choice map first.
Otherwise the design may silently retain the default mapping.
For an already gate-level ripple adder, recover the word-level adder with
extract_fa -fa -ha; opt_clean; lift_adder only when the selected Yosys fork
supports those commands. A stock tool without lift_adder cannot execute that
path. Run native combinational equivalence after the transformation and native
timing on the resulting mapped design. An unproven equivalence result or a
missing timing result leaves that part of the proposed fix open.
native tool review — registered-output / sampling-latency notes
Surfaces outputs that are registered (valid +1 cycle after their inputs). Confirm each against the spec's required valid-cycle — an off-by-one-cycle output (Moore/pipelined vs combinational) is a classic spec miss.
Read the input timing convention and native simulation/formal results before changing output registration. Preserve the specified latency and handshake behavior through any synthesis repair.
Repair the failed native step
- Read the failed tool command and its actual diagnostic.
- Reproduce the design, configuration or tool cause with the smallest relevant native execution.
- Fix that cause and rerun the affected native steps using the same original constraints and limits.
- Review the new result, functional behavior and any affected timing, area, power or physical checks before reporting completion.
⛔ ECO spare-cell preservation (mandatory)
Compare the native netlist or implementation database before and after optimization. Preserve every unused ECO spare, its keep attributes and the reserved pads; an unintentionally removed spare must be restored.
Constant nets need a tie-cell pass before PnR (captured v0.1.95)
A gate netlist that drives any constant bit (1'h0 / 1'h1 — from CRC tables, output
clamps, tie-offs, zeroed unused outputs) as a bare net will fail TritonRoute with
DRT-0305 (zero_ net) / DRT-0199 during detailed route. The fix is a tie-cell pass:
map the constants to the PDK's dedicated tie cell (sky130 sky130_fd_sc_hd__conb_1,
dual HI/LO output) and split shared nets — in yosys, after abc and before write_verilog:
setundef -zero; hilomap -hicell <TIE_CELL> <HI_PIN> -locell <TIE_CELL> <LO_PIN>; splitnets; clean
For a design that requires tie cells, run setundef before hilomap and opt_clean -purge before hilomap so newly created tie instances remain in the final native netlist.
setundef -zeroBEFOREhilomap. A function with don't-care output bits (yosys emits1'hxfor unreachable/dead bits — common in framing/CRC logic) surviveshilomapas a barezero_/xnet that TritonRoute still rejects with DRT-0305.setundef -zeroresolves the x bits to 0 first sohilomapcan tie them.- Do NOT run
opt_clean(orclean -purge) AFTERhilomap.opt_cleantreats the just- inserted tie cells as removable constant drivers and DELETES them, re-introducing the bare constant nets. Use plainclean(or nothing). On HDLC,hilomap; opt_cleanlet DRT-0305 fire (0 surviving tie cells);setundef -zero; hilomap; splitnets; cleankept all 1780conb_1cells and PnR ran clean. (This also satisfies the ECO spare-cell rule above — neveropt_cleanaway inserted cells.)
Read the actual Yosys script/log and emitted netlist to confirm legal tie-cell mapping where the target library requires it. Keep tech mapping, tie mapping and netlist writing in the native tool-supported order.
Path note (the recurring trap): phase3_one_shot_runner.py ALREADY does a tie-cell pass
automatically (it discovers the tie cell from the liberty and inserts hilomap). But the
bare MCP eda_synth→eda_pnr path (what the doc→GDS pilots drive) does NOT — its
yosys script is synth; dfflibmap; abc; clean; write_verilog with no hilomap, and it only
emits a zero_net_hint rather than auto-applying the fix. So when driving the bare MCP
path, either (a) re-synth with the refined setundef -zero; hilomap; splitnets; clean pass
above via eda_run_tcl before eda_pnr, or (b) drive synth through the phase3 runner which
handles it. The cell count is unchanged — the tie cells replace the bare constants 1:1.
Forward-validated SENT→QSPI→HDLC→SpaceWire (4 pilots, clean first-pass each). Tracked for a permanent eda_synth fix in
ORGANIC-20260531-mcp-eda-synth-missing-hilomap-tiecells.
Skill: Match structural evidence to the claimed representation
Separate functional behavior, source syntax, generic mapped cells and physical library cells. A binary truth-table test establishes function. A procedural-if requirement also needs its stated syntax and relevant four-state semantics. An explicit state encoding needs encoding/reset/transition evidence. A mux-only or minimum-cell claim needs an actual mapped graph in the declared cell model; universal X-propagation assertions over behavioral RTL do not prove topology.
Freeze the source and retain the native command, tool identity and emitted netlist. Check cell types/counts and binary source/netlist equivalence separately. Prove a model-specific lower bound before claiming minimality; otherwise report only the observed mapped count. Do not relabel generic mux mapping as physical standard-cell qualification.
If a requested native mapping target fails, preserve that failure and track
the generating tool defect. Where the contract permits generic two-input-LUT
decomposition, native Yosys abc -lut 2; lut2mux; opt_expr; opt_clean can supply
an independently inspected mux graph. Its successful result neither repairs
the failed target nor changes the allowed cell model. A bad review test is
retained and corrected through the normal fresh-review/supersession mechanism;
correct RTL is not rewritten merely to satisfy an invalid structural proxy.
Why not Bucket A: existing native tools generate and inspect graphs; choosing the applicable representation and proving a lower bound require the current input's circuit model. No benchmark-specific structural oracle is added.
Captured rule
SHA256: request native reset-aware clock gating, then prove the design point
A clockgate minimum alone does not mean a resettable bank was gated. Read the
native Yosys cell census: SHA256 still had 1065 $_SDFFE_* FFs after an
ordinary clockgate arm. Native -gate_srst folds reset-over-enable as
CE | SRST; use that native option, not a handwritten clock expression or
plugin-side netlist edit. If explicit ICG mappings are absent, let native Yosys
qualify the ICG from the synthesis Liberty; do not treat an unmapped no-op as a
gated arm. Native -max_net_size can bound the fanout each ICG hands to CTS.
Program capture: LibreLane fork PR #50 (66ca870, base 03d6469) exposes
SYNTH_CLOCKGATE_SYNC_RESET (default false) and
SYNTH_CLOCKGATE_MAX_WIDTH (default unset), plus native Liberty qualification
when a requested arm has no explicit ICG names. No-gating defaults, activity,
original signoff bounds and explicit mapping precedence remain unchanged.
Native full fork suite: 252 PASS / 5 new-test FAIL -> 257 PASS / 0 FAIL,
with 5 existing skips on both. A follow-up native test file is 13/13
PASS, including four 1000-cycle exact waveform comparisons (explicit vs
Liberty-qualified ICGs, unlimited vs maximum-8 bank size). Mixed synchronous
reset priority, asynchronous reset and negative-edge banks retain their
behavior; 32 FFs use 3 ICGs or 4 ICGs respectively. The native automatic chooser
must reject a smaller unqualified decoy. No previous golden/assertion was
loosened. Jobs: sha256-librelane-native-clockgate-base0476-oai,
sha256-librelane-clockgate-reset-initialized0476-oai, and
sha256-librelane-native-icg-qualification0476-oai, image 0.4.76.
SHA256 native synthesis at minimum width 8 changes 512 FF / 16 ICG -> 1568 FF / 19 ICG with reset-aware gating. A bounded routed candidate meets the original nine-corner setup/hold limits at +0.098435 / +0.127717 ns, but TT 7.092685 mW still FAILs <5mW. A receiver/repair candidate reaches +0.420757 / +0.074131 ns and TT 5.327472 mW, also still FAIL. A lower 4.838773 mW report came after native sizing/routing failures and is NOT an accepted power closure. More importantly, native EQY disproves 288 partitions on a gated candidate with the existing single-clock preparation. Do not adopt any such candidate or count a newly closed design step until the checker-native clock model/equivalence proof and all original gates pass.
Sparse state registers keep their codes through native synthesis
Yosys fsm_recode re-encodes every state machine fsm_detect extracts. A
register the RTL declares sparse (a sparse-FSM flop, a Hamming-separated state
enum, or an explicit fsm_encoding attribute) must keep its codes: the netlist
would still be equivalent at its key points, but it would no longer be the
specified design. The native flow config (flow_config.build_config) passes
sparse_fsm_detect's registers and flop instances to LibreLane's
SYNTH_PRESERVE_FSM_REGISTERS / SYNTH_PRESERVE_FSM_INSTANCES; a design
without such registers gets an unchanged config. Read the proof in the native
synthesis log, not in the config: count the Recoding FSM lines and check
that none names a declared sparse register.
Measured on the OpenTitan AES hard macro (sky130A, stock 0.4.81, default
settings): 15 -> 9 Recoding FSM lines, the six removed being the control
and counter sparse state flops; 21,178 -> 21,022 cells and
170,442.2176 -> 171,560.7904 um2. This does NOT close netlist equivalence
on that design: the partition result is unchanged (90 -> 44 -> 18 partitions,
one unproved cone), so do not expect an encoding fix to shrink a proof cone.