synthesis

name	synthesis
description	Use when running Design Compiler synthesis, analyzing timing/area/power reports, supplementing SDC exceptions, or re-synthesizing after RTL changes; not for power analysis or static timing.

Synthesis

Your sole responsibility: carry this module's declared timing exceptions into the SDC, converge Design Compiler against it, and close the run through the synthesis CLI.

Iron Rule

• Write only under {workdir}. Every injected input location is read-only, as is every other stage's output.
• Scripts are black boxes, never Read their source. Invoke them per this skill's documented command lines (flags via --help); on a non-zero exit act on the documented failure protocol (stderr, stdout verdict), not the source. Sole exception: debugging a suspected bug in a script itself.

What you read, and what you edit

<skill> is this skill's own base directory, named on the first line of this file.

{workdir}/dispatch.json carries the inputs table below, so <key> denotes a location and you read <key>/<subpath>. It also carries scope and caused_by when the kernel knows what changed since your last run: those narrow which inherited exceptions you re-check and which violations you triage, never which declarations you render — step 2 carries all of them every round, because the SDC dc_shell reads is rebuilt every round.

Path	Use
<annotations>/constraint-annotations.json	The sdc block per child: every timing exception and generated clock this RTL implies, in real module names. Its authors declared it and this stage is its only consumer. Schema: skills/rtl-design/references/constraint-annotations.schema.json.
<rtl>/rtl-files.json	Per-child file layout, which bootstrap turns into scripts/rtl_load.tcl. The RTL itself is under <rtl> too, and step 2 reads it for divider ratios. Schema: skills/rtl-design/references/rtl-files.schema.json.
<sdc>/constraints/<TOP>.sdc	Clocks and IO delays from specification. bootstrap reads it every round, so a correction here arrives on its own; it is not yours to restate or override.
<ppa>/ppa.json	The area and slack targets this run is judged against. finalize reads them itself; you read them when deciding which side of a PPA miss is wrong. Schema: skills/specification/references/ppa.schema.json.

LIB_DB must be in the environment before make: env.sh refuses to run without it, and the placeholder in scripts/config.tcl is a fallback for a dc_shell started outside the Makefile, not a second way to set it. Exporting it after step 1 is fine.

One file under {workdir} is yours to edit, and it reaches you holding the previous round's work rather than the specification SDC:

• constraints.sdc: every exception, every library value, and the # notes: that say why.

Treat what is in it as work you inherited. Re-check each exception against this run's reports and delete one whose path no longer exists, but re-deriving a set you already have costs a full re-synthesis per round. Everything else under {workdir} is produced by the tools you invoke, and finalize enumerates it into artifacts[] for you.

Workflow

1. Deploy

Run bootstrap to lay down the run scaffold:

python3 <skill>/scripts/synthesis/__main__.py bootstrap --workdir {workdir} [--top <TOP>]

It generates scripts/rtl_load.tcl and scripts/config.tcl from the rtl-design file layout, and assembles constraints.sdc from the specification SDC plus your inherited constraints.local.sdc. It aborts when {workdir}/Makefile already exists (the kernel-written dispatch.json does not count as "deployed"), and reads the top-module name from manifest.module when --top is omitted. Non-zero exit: stderr names the cause, and nothing was deployed, so the retry is not blocked. make is the interface to everything it deployed.

2. Constrain

Union the sdc block across every child of <annotations>/constraint-annotations.json and render all three categories into constraints.sdc before you run anything:

sidecar key	what it carries	what you write
create_generated_clock	{module, pin} — where a divider or PLL output leaves that child's RTL	create_generated_clock on that pin. -source is the master clock the specification SDC already declares; the divide factor comes from that module's RTL under <rtl>
set_multicycle_path	one free-form description per exception its author knows the design needs	set_multicycle_path naming the real startpoint / endpoint
set_false_path	the same, for architecturally unreachable paths	set_false_path naming the real startpoint / endpoint

Every category is always present, so an empty array is that child's claim to have none. These are design facts their authors declared rather than suppressions you are guessing at, which is why all three go in one pass: each one you leave for dc_shell to surface costs a full synthesis iteration to discover, and this sidecar is the only place rtl-design can state them.

Transcribe, never invent. lint-cdc reads this same sidecar for its SGDC side, so an exception you add on your own authority has no counterpart there and the two constraint sets diverge silently. A path nobody declared is step 3's to report, not yours to except.

Everything you write goes in constraints.local.sdc, which bootstrap sources after the seed. Tcl takes the last assignment, so settling one of the seed's placeholders is a line here, not an edit there: the set_clock_uncertainty -setup / -hold values its ;# notes flag, and set_drive / set_load, which it carries for no port — add those only where the IO cell library documents them. Anything you leave at a placeholder, and anything you decide not to add, needs a # notes: line saying why: this file is promoted, and the next reader cannot tell a measured margin from a default or an omission from an oversight.

constraints.sdc is the file dc_shell reads and is generated every round from the seed plus your local file. Editing it is pointless — the next round overwrites it — and that is what lets a corrected clock upstream reach the tool without touching what you measured.

3. Converge

make synthesis runs dc_shell and outlives the foreground Bash timeout. Launch it as one detached background job (run_in_background=True) from {workdir}, stay in this turn until it exits, then read run.log once. The Makefile tees that log, so poll it — nothing resumes a subagent when a job it started finishes.

Read the violated paths in reports/timing_setup.rpt, keeping each one's startpoint, endpoint and slack. Step 2 already carried in every exception the design declares, so a path that is still violating is one of two things:

• A declaration you rendered wrong — the description named a path and your SDC command does not match it. Fix the command and re-run.
• A path nobody declared — a real violation. Stop iterating and go to step 4. Its negative slack fails the timing_slack_ns target on its own, so the gate writes the violations[] row; what it cannot write is who must fix it.

Excepting the second kind here on your own judgement is the one way this stage can except its way to a passing PPA verdict. If the path really is multicycle or false, its author is the one who says so: name rtl-design in step 4 and it comes back declared, in the sidecar lint-cdc reads too.

A non-zero make ends the run with nothing to grade, so go straight to step 4 carrying the cause you read in run.log.

4. Close

Run finalize to write the envelope. Every run ends here, a dc_shell that never reached the reports included, and you never hand-assemble it:

python3 <skill>/scripts/synthesis/__main__.py finalize \
  --workdir {workdir} [--fix-owner <rule>] \
  [--fail-reason "<cause>"]

It judges the PPA gate (worst setup slack = min of Critical Path Slack across every clock-group block; area = Total cell area) against the targets it reads from <ppa>/ppa.json itself — area_um2 and timing_slack_ns only, an absent file or dim leaving that dimension ungated — records both measurements as stage_specific.ppa_actual[], reads the DC version off the report header, and enumerates artifacts[]. A clean gate is not enough for a pass: all three of out/*_syn.{v,sdc,sdf} must be on disk, and an incomplete set is a tooling fail rather than a promoted synthesis the downstream stages cannot read.

The flags carry what the reports cannot:

• --fail-reason, which fills stage_specific.fail_reason, when dc_shell produced nothing gradeable: no license, an analyze / elaborate / link / check_design / compile_ultra abort, or a crash after the reports landed. You are the one who read run.log. Supplying it is itself the declaration of failure, so it wins over the gate and forces status=fail even where the reports parse clean; write the cause you actually read rather than a category, since nothing parses it.
• --fix-owner on every failure, tool and license failures included, since it is what fills stage_specific.fix_owner. A fail_reason naming the guilty stage in prose while the flag was omitted reads to the caller as "this stage could not tell", and brings a human in to re-derive an answer you already had. A PPA gate compares a measured value against a target and either side can be wrong, so before naming rtl-design, read <ppa>/ppa.json: a dim whose unit disagrees with the number stored in it — an area_um2 target holding a NAND2 gate count, say — makes a conforming design look over-budget, and no rebuild converges against it. Name specification when the target is what is malformed, and omit the flag only when you have read both sides and still cannot name an owner.

Exit 0 means written, pass or fail. Exit 2 is BLOCKED and never a status=fail: an empty --fail-reason, or a program exception. stderr names which.

Return Contract

Emit STATUS: DONE as your last line once result.json exists, or STATUS: BLOCKED <one-line reason> when nothing could be written. What runs next is the caller's decision, taken from result.json.