Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ OpenROAD run to compare the results.

https://github.com/user-attachments/assets/deadc1db-22f3-4c32-8f59-9bbca4aa1ccd

46 seconds, no audio. [Download the MP4](https://github.com/keplertech/22b/raw/refs/heads/main/examples/backend/gcd/reference/media/demo.mp4)
48 seconds, no audio. [Download the MP4](https://github.com/keplertech/22b/raw/refs/heads/main/examples/backend/gcd/reference/media/demo.mp4)
if the inline player is unavailable.

## Start
Expand Down
34 changes: 30 additions & 4 deletions examples/backend/gcd/reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,21 +13,34 @@ does not change the shared policy for exploratory partial/inconclusive proofs.
Verification uses the Python-backed Kepler Formal MCP, not the legacy Nix CLI.

Small mapped SKY130HD GCD design: 249 original leaf cells, 4.36 ns clock period.
Five serial majority gates (`_215_` through `_219_`) are replaced with a 31-gate
Five serial majority gates (`_215_` through `_219_`) are replaced with a 23-gate
generate/propagate prefix network. All five original output nets are reused,
including their side consumers. Registers and cycle boundaries stay unchanged.

The arithmetic identity is `majority(a,b,c) = (a & b) | ((a | b) & c)`.
Computing group generate/propagate terms in parallel reduces carry dependence.
All eleven inputs arrive at about the same time, so the carry-in is folded
into bit 0 and the terms form a balanced tree of four levels. The cells
alternate polarity (NAND, NOR, AOI, OAI), so each level is a single stage.
Fewer logic levels, not fewer initial gates, is the timing hypothesis. The
edited design has 275 leaf cells before physical optimization.
edited design has 267 leaf cells before physical optimization.

The packaged flow repairs setup timing on placement estimates and stops at
about zero slack; routing then costs several tens of picoseconds. An edit
therefore needs margin of its own. An earlier 31-gate network of two-stage
AND/OR cells, with the carry-in added last, had five levels. Measured with
the pinned packages in November 2026, it ended at -0.025 ns after routing;
this one needed no repair and ended at +0.205 ns. Measure again after any
package change.

## Contents

- [input.v](../input.v): original mapped design, never edited in place.
- [constraints.sdc](../constraints.sdc): original clock and I/O constraints.
- [edit.py](edit.py): reviewed standalone NajaEDA rewrite from the recorded demo,
with additional input/name/output guards. Not a fresh model generation.
- [edit.py](edit.py): reviewed standalone NajaEDA rewrite, with input/name/output
guards. Not a fresh model generation.
- [media/demo.mp4](media/demo.mp4): 48-second walk-through of this replay with the
pinned packages. Its numbers, log lines and layout images come from that run.
- [live_session.py](live_session.py): optional in-memory replay with two
cumulative edits, no design exports, and full SEC after each edit.
- [request.md](request.md): saved, solution-specific request for this reference.
Expand Down Expand Up @@ -112,10 +125,16 @@ without this directory in its initial context.
python -m py_compile "$EXAMPLE/reference/edit.py"
python "$EXAMPLE/reference/edit.py" --liberty "$LIBERTY" \
--input "$EXAMPLE/input.v" --output "$RUN/candidate.v" | tee "$RUN/edit.log"
python tools/edit_validation.py --liberty "$LIBERTY" --verilog "$RUN/candidate.v"
```

The script refuses an existing output file and checks the original carry chain
before editing. Run without Python's `-O` flag, which disables its assertions.
Each new gate is `ppa_cla_<term>` and the new net it drives `ppa_cla_<term>_net`.
Verilog allows no instance with the name of a net. NajaEDA, Kepler Formal and
OpenROAD accept one, but OpenROAD then times the design without the extracted
parasitics of those nets. The second command checks the exported file; the
automated replay runs it as part of the edit stage.
Input hashes and the 2,048-case Boolean truth table are checked by the offline
tests; those checks do not replace SEC of the exported candidate.

Expand Down Expand Up @@ -185,6 +204,13 @@ dual-rail steady-state abstraction. Setup improved by about 600 ps, but the
positive margin was only 0.132 ps. Power used the same default activity
assumptions and this is a typical-corner demonstration, not multi-corner signoff.

That run used the earlier 31-gate network, in which each new net also had the
name of the gate driving it. In the packaged flow such names make OpenROAD drop the extracted
parasitics of those nets when it reads the SPEF back (`pin ... not found`) and
report about 0.1 ns more setup slack than the same layout has. The historical
image was not rerun: treat its candidate slack as unverified and probably
optimistic.

The full source revision and image are recorded in
[historical-results.json](historical-results.json). A new tool package requires
new baseline and candidate measurements; no particular improvement is guaranteed.
94 changes: 51 additions & 43 deletions examples/backend/gcd/reference/edit.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,56 +28,64 @@ def edit(top):
for i in range(1, len(instances)):
assert instances[i].get_term('C').get_upper_net() == wires[f'x{i-1}']

# Carry out of bit i: x_i = g_i | p_i & x_(i-1), with g = a & b, p = a | b and x_(-1) = c0.
# All inputs arrive together, so the carry-in is folded into bit 0 and the terms form a
# balanced tree. A name starting with n is an inverted term: gates alternate polarity,
# so every level is a single-stage cell. Rows: cell, output, output pin, inputs.
rows = [
('sky130_fd_sc_hd__and2_1', 'g0', 'a0', 'b0', '-', '-', '-'),
('sky130_fd_sc_hd__or2_1', 'p0', 'a0', 'b0', '-', '-', '-'),
('sky130_fd_sc_hd__and2_1', 'g1', 'a1', 'b1', '-', '-', '-'),
('sky130_fd_sc_hd__or2_1', 'p1', 'a1', 'b1', '-', '-', '-'),
('sky130_fd_sc_hd__and2_1', 'g2', 'a2', 'b2', '-', '-', '-'),
('sky130_fd_sc_hd__or2_1', 'p2', 'a2', 'b2', '-', '-', '-'),
('sky130_fd_sc_hd__and2_1', 'g3', 'a3', 'b3', '-', '-', '-'),
('sky130_fd_sc_hd__or2_1', 'p3', 'a3', 'b3', '-', '-', '-'),
('sky130_fd_sc_hd__and2_1', 'g4', 'a4', 'b4', '-', '-', '-'),
('sky130_fd_sc_hd__or2_1', 'p4', 'a4', 'b4', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g11', '-', '-', 'p1', 'g0', 'g1'),
('sky130_fd_sc_hd__and2_1', 'p11', 'p1', 'p0', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g21', '-', '-', 'p2', 'g1', 'g2'),
('sky130_fd_sc_hd__and2_1', 'p21', 'p2', 'p1', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g31', '-', '-', 'p3', 'g2', 'g3'),
('sky130_fd_sc_hd__and2_1', 'p31', 'p3', 'p2', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g41', '-', '-', 'p4', 'g3', 'g4'),
('sky130_fd_sc_hd__and2_1', 'p41', 'p4', 'p3', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g22', '-', '-', 'p21', 'g0', 'g21'),
('sky130_fd_sc_hd__and2_1', 'p22', 'p21', 'p0', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g32', '-', '-', 'p31', 'g11', 'g31'),
('sky130_fd_sc_hd__and2_1', 'p32', 'p31', 'p11', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g42', '-', '-', 'p41', 'g21', 'g41'),
('sky130_fd_sc_hd__and2_1', 'p42', 'p41', 'p21', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'g44', '-', '-', 'p42', 'g0', 'g42'),
('sky130_fd_sc_hd__and2_1', 'p44', 'p42', 'p0', '-', '-', '-'),
('sky130_fd_sc_hd__a21o_1', 'x0', '-', '-', 'p0', 'c0', 'g0'),
('sky130_fd_sc_hd__a21o_1', 'x1', '-', '-', 'p11', 'c0', 'g11'),
('sky130_fd_sc_hd__a21o_1', 'x2', '-', '-', 'p22', 'c0', 'g22'),
('sky130_fd_sc_hd__a21o_1', 'x3', '-', '-', 'p32', 'c0', 'g32'),
('sky130_fd_sc_hd__a21o_1', 'x4', '-', '-', 'p44', 'c0', 'g44'),
# Bit 0 takes the carry-in: nx0 = !(g0 | p0 & c0).
('sky130_fd_sc_hd__and2_1', 'g0', 'X', {'A': 'a0', 'B': 'b0'}),
('sky130_fd_sc_hd__or2_1', 'p0', 'X', {'A': 'a0', 'B': 'b0'}),
('sky130_fd_sc_hd__a21oi_1', 'nx0', 'Y', {'A1': 'p0', 'A2': 'c0', 'B1': 'g0'}),
('sky130_fd_sc_hd__inv_1', 'x0', 'Y', {'A': 'nx0'}),
# Inverted generate and propagate of bits 1 to 4.
('sky130_fd_sc_hd__nand2_1', 'ng1', 'Y', {'A': 'a1', 'B': 'b1'}),
('sky130_fd_sc_hd__nor2_1', 'np1', 'Y', {'A': 'a1', 'B': 'b1'}),
('sky130_fd_sc_hd__nand2_1', 'ng2', 'Y', {'A': 'a2', 'B': 'b2'}),
('sky130_fd_sc_hd__nor2_1', 'np2', 'Y', {'A': 'a2', 'B': 'b2'}),
('sky130_fd_sc_hd__nand2_1', 'ng3', 'Y', {'A': 'a3', 'B': 'b3'}),
('sky130_fd_sc_hd__nor2_1', 'np3', 'Y', {'A': 'a3', 'B': 'b3'}),
('sky130_fd_sc_hd__nand2_1', 'ng4', 'Y', {'A': 'a4', 'B': 'b4'}),
('sky130_fd_sc_hd__nor2_1', 'np4', 'Y', {'A': 'a4', 'B': 'b4'}),
# Pairs of bits: G = g_hi | p_hi & g_lo and P = p_hi & p_lo.
('sky130_fd_sc_hd__o21ai_1', 'G21', 'Y', {'A1': 'np2', 'A2': 'ng1', 'B1': 'ng2'}),
('sky130_fd_sc_hd__nor2_1', 'P21', 'Y', {'A': 'np2', 'B': 'np1'}),
('sky130_fd_sc_hd__o21ai_1', 'G43', 'Y', {'A1': 'np4', 'A2': 'ng3', 'B1': 'ng4'}),
('sky130_fd_sc_hd__nor2_1', 'P43', 'Y', {'A': 'np4', 'B': 'np3'}),
# Bits 1 to 4 as one group, inverted.
('sky130_fd_sc_hd__a21oi_1', 'nG41', 'Y', {'A1': 'P43', 'A2': 'G21', 'B1': 'G43'}),
('sky130_fd_sc_hd__nand2_1', 'nP41', 'Y', {'A': 'P43', 'B': 'P21'}),
# The carries, on the original nets.
('sky130_fd_sc_hd__o21ai_1', 'x1', 'Y', {'A1': 'np1', 'A2': 'nx0', 'B1': 'ng1'}),
('sky130_fd_sc_hd__a21oi_1', 'nx2', 'Y', {'A1': 'P21', 'A2': 'x0', 'B1': 'G21'}),
('sky130_fd_sc_hd__inv_1', 'x2', 'Y', {'A': 'nx2'}),
('sky130_fd_sc_hd__o21ai_1', 'x3', 'Y', {'A1': 'np3', 'A2': 'nx2', 'B1': 'ng3'}),
('sky130_fd_sc_hd__o21ai_1', 'x4', 'Y', {'A1': 'nP41', 'A2': 'nx0', 'B1': 'nG41'}),
]

# Validate every new name before mutating the candidate.
for _, output_key, *_ in rows:
name = f'ppa_cla_{output_key}'
assert top.get_child_instance(name) is None, f'Instance already exists: {name}'
if output_key not in wires:
# Validate every new name before mutating the candidate. Verilog keeps a
# module's instances, nets and ports in one name space, which NajaEDA does
# not enforce: a new gate and the net it drives get different names, and
# each must be unused by all three kinds. A row reads earlier rows only.
driven = set(key for key in wires if key[0] != 'x')
for _, output_key, _, inputs in rows:
assert all(key in driven for key in inputs.values()), f'Term read before it is driven: {output_key}'
driven.add(output_key)
instance_name = f'ppa_cla_{output_key}'
new_names = [instance_name] if output_key in wires else [instance_name, f'{instance_name}_net']
for name in new_names:
assert top.get_child_instance(name) is None, f'Instance already exists: {name}'
assert top.get_net(name) is None, f'Net already exists: {name}'
assert top.get_term(name) is None, f'Port already exists: {name}'

for model, output_key, *inputs in rows:
for model, output_key, output_pin, inputs in rows:
instance_name = f'ppa_cla_{output_key}'
if output_key not in wires:
wires[output_key] = create_net(top, instance_name)
wires[output_key] = create_net(top, f'{instance_name}_net')
new_inst = top.create_child_instance(model=model, name=instance_name)
for pin_name, input_key in zip(['A', 'B', 'A1', 'A2', 'B1'], inputs):
if input_key != '-':
connect_term(new_inst.get_term(pin_name), wires[input_key])
connect_term(new_inst.get_term('X'), wires[output_key])
for pin_name, input_key in inputs.items():
connect_term(new_inst.get_term(pin_name), wires[input_key])
connect_term(new_inst.get_term(output_pin), wires[output_key])

for inst in instances:
inst.delete()
Expand All @@ -104,6 +112,6 @@ def edit(top):
edit(top)
after = len(list(top.get_leaf_children()))
top.dump_verilog(a.output)
print(f'NAJA_EDIT: replaced 5 majority gates with 31 prefix-network gates; {before} -> {after} leaf instances')
print(f'NAJA_EDIT: replaced 5 majority gates with 23 prefix-network gates; {before} -> {after} leaf instances')
print('NAJA_EDIT: existing boundary nets reused; registers unchanged')
print(f'OUTPUT={a.output}')
2 changes: 1 addition & 1 deletion examples/backend/gcd/reference/historical-results.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,5 @@
"baseline": {"setup_ns": -0.5998004485079101, "hold_ns": 0.4804596856359008, "area_um2": 3931, "estimated_power_mw": 1.49, "drc": 0},
"candidate": {"setup_ns": 0.00013233858827810954, "hold_ns": 0.48828492631283044, "area_um2": 3636, "estimated_power_mw": 1.34, "drc": 0},
"proof": {"mode": "sec", "status": "proved", "covered_outputs": 18, "existing_outputs": 18, "proved_outputs": 18, "skipped_outputs": 0, "k": 5, "abstraction": "dual_rail_steady"},
"caveats": ["Historical demonstration; not rerun with the new Nix packages", "Single typical corner", "Power estimate with default activity", "Candidate setup margin is only about 0.132 ps"]
"caveats": ["Historical demonstration; not rerun with the new Nix packages", "Single typical corner", "Power estimate with default activity", "Candidate setup margin is only about 0.132 ps", "Candidate nets were named like their driving gates, which can drop their extracted parasitics: its setup slack is unverified and probably optimistic"]
}
4 changes: 2 additions & 2 deletions examples/backend/gcd/reference/live_session.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@
assert gate is not None
assert top.get_net("session_buffer_stage") is None
assert top.get_child_instance("session_buffer") is None
output = gate.get_term("X").get_upper_net()
output = gate.get_term("Y").get_upper_net()
stage = top.create_net("session_buffer_stage")
gate.get_term("X").connect_upper_net(stage)
gate.get_term("Y").connect_upper_net(stage)
buf = top.create_child_instance(model="sky130_fd_sc_hd__buf_1", name="session_buffer")
buf.get_term("A").connect_upper_net(stage)
buf.get_term("X").connect_upper_net(output)
Expand Down
Binary file modified examples/backend/gcd/reference/media/demo-preview.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified examples/backend/gcd/reference/media/demo.mp4
Binary file not shown.
10 changes: 9 additions & 1 deletion scripts/gcd_reference_regression.py
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,10 @@ def physical_summary(directory):
for marker in ("GCD_COMPLETE=1", "GCD_ROUTED=1", "GCD_FINAL_DRC=0"):
if not re.search(r"(?m)^" + re.escape(marker) + r"\s*$", log):
raise ValueError(f"Missing {marker}: {directory}")
# Extracted parasitics that could not be attached leave the reported timing optimistic.
lost = re.findall(r"(?m)^\[WARNING STA-\d+\] \S+ line \d+, (?:pin|net|instance) \S+ not found\.?\s*$", log)
if lost:
raise ValueError(f"{len(lost)} parasitics were not annotated ({lost[0].strip()}): {directory}")
for name in REPORTS:
path = directory / "reports" / (name + ".rpt")
# A violations-only report can be empty when the checks are clean.
Expand Down Expand Up @@ -215,7 +219,7 @@ def input_hashes():
return {str(path.relative_to(ROOT)): digest(path) for path in
(EXAMPLE / "input.v", EXAMPLE / "constraints.sdc", REFERENCE / "edit.py",
PLATFORM / "run.tcl", ROOT / "toolchain.json", ROOT / "tools/python-requirements.txt",
ROOT / "tools/naja-scope/requirements.txt",
ROOT / "tools/naja-scope/requirements.txt", ROOT / "tools/edit_validation.py",
ROOT / "tools/kepler-formal/verify.py", ROOT / "tools/kepler-formal/mcp-requirements.txt")}


Expand Down Expand Up @@ -303,6 +307,10 @@ def stage(name, work, fixture, timeout):
"--input", str(design), "--output", str(work / "candidate.v")], timeout=timeout)
if not (work / "candidate.v").is_file():
raise ValueError("Edit did not export a candidate")
# An instance named like a net is not valid Verilog: SEC passes it, OpenROAD mis-times it.
run_command(work / "edit-names", [sys.executable, str(ROOT / "tools/edit_validation.py"),
"--liberty", str(liberty), "--verilog", str(work / "candidate.v")],
timeout=timeout)
metadata["candidate_sha256"] = digest(work / "candidate.v")
elif name == "proof":
summary = SEC.run_sec(directory, design, work / "candidate.v", [liberty], timeout=timeout)
Expand Down
Loading
Loading