diff --git a/README.md b/README.md index dc31fcb..0f5cd3b 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/examples/backend/gcd/reference/README.md b/examples/backend/gcd/reference/README.md index 2f8354f..0fd5996 100644 --- a/examples/backend/gcd/reference/README.md +++ b/examples/backend/gcd/reference/README.md @@ -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. @@ -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_` and the new net it drives `ppa_cla__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. @@ -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. diff --git a/examples/backend/gcd/reference/edit.py b/examples/backend/gcd/reference/edit.py index 9a24e5d..598c94c 100644 --- a/examples/backend/gcd/reference/edit.py +++ b/examples/backend/gcd/reference/edit.py @@ -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() @@ -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}') diff --git a/examples/backend/gcd/reference/historical-results.json b/examples/backend/gcd/reference/historical-results.json index 6c885b5..5cdd6a8 100644 --- a/examples/backend/gcd/reference/historical-results.json +++ b/examples/backend/gcd/reference/historical-results.json @@ -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"] } diff --git a/examples/backend/gcd/reference/live_session.py b/examples/backend/gcd/reference/live_session.py index 8c4525a..e0e6805 100644 --- a/examples/backend/gcd/reference/live_session.py +++ b/examples/backend/gcd/reference/live_session.py @@ -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) diff --git a/examples/backend/gcd/reference/media/demo-preview.jpg b/examples/backend/gcd/reference/media/demo-preview.jpg index 1803f06..829d846 100644 Binary files a/examples/backend/gcd/reference/media/demo-preview.jpg and b/examples/backend/gcd/reference/media/demo-preview.jpg differ diff --git a/examples/backend/gcd/reference/media/demo.mp4 b/examples/backend/gcd/reference/media/demo.mp4 index 4a67ded..fe30bf5 100644 Binary files a/examples/backend/gcd/reference/media/demo.mp4 and b/examples/backend/gcd/reference/media/demo.mp4 differ diff --git a/scripts/gcd_reference_regression.py b/scripts/gcd_reference_regression.py index 5e789d9..ab4f66b 100644 --- a/scripts/gcd_reference_regression.py +++ b/scripts/gcd_reference_regression.py @@ -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. @@ -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")} @@ -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) diff --git a/tests/test_gcd.py b/tests/test_gcd.py index b447c74..06daab8 100644 --- a/tests/test_gcd.py +++ b/tests/test_gcd.py @@ -59,6 +59,7 @@ def __init__(self): pins["C"] = Pin(self.nets["c0" if i == 0 else f"x{i-1}"]) self.gates[f"_{215+i}_"] = Gate("sky130_fd_sc_hd__maj3_2", pins) self.side_loads = [Pin(self.nets[f"x{i}"]) for i in range(5)] + self.ports = {} def get_child_instance(self, name): return self.gates.get(name) @@ -66,6 +67,9 @@ def get_child_instance(self, name): def get_net(self, name): return self.nets.get(name) + def get_term(self, name): + return self.ports.get(name) + def create_net(self, name): if name in self.nets: raise ValueError(name) @@ -73,14 +77,27 @@ def create_net(self, name): return self.nets[name] def create_child_instance(self, *, model, name): - pins = ("A1", "A2", "B1", "X") if "__a21o_" in model else ("A", "B", "X") + _, output_pin, function = CELLS[model] + pins = (*function.__code__.co_varnames[:function.__code__.co_argcount], output_pin) self.gates[name] = Gate(model, {pin: Pin() for pin in pins}) return self.gates[name] +# The cells the rewrite uses: output pin and Boolean function of the Liberty cell. +CELLS = {f"sky130_fd_sc_hd__{name}_1": (name, pin, function) for name, pin, function in ( + ("and2", "X", lambda A, B: A & B), + ("or2", "X", lambda A, B: A | B), + ("nand2", "Y", lambda A, B: 1 - (A & B)), + ("nor2", "Y", lambda A, B: 1 - (A | B)), + ("inv", "Y", lambda A: 1 - A), + ("a21oi", "Y", lambda A1, A2, B1: 1 - ((A1 & A2) | B1)), + ("o21ai", "Y", lambda A1, A2, B1: 1 - ((A1 | A2) & B1)), +)} + + class GcdTests(unittest.TestCase): def test_truth_table_all_2048_inputs_and_five_outputs(self): - self.assertEqual(len(ROWS), 31) + self.assertEqual(len(ROWS), 23) for bits in itertools.product((0, 1), repeat=11): values = dict(zip([f"a{i}" for i in range(5)] + [f"b{i}" for i in range(5)] + ["c0"], bits)) expected = [] @@ -88,18 +105,12 @@ def test_truth_table_all_2048_inputs_and_five_outputs(self): for i in range(5): carry = int(values[f"a{i}"] + values[f"b{i}"] + carry >= 2) expected.append(carry) - for model, output, *inputs in ROWS: - args = [values[key] for key in inputs if key != "-"] - if "__and2_" in model: - result = args[0] & args[1] - elif "__or2_" in model: - result = args[0] | args[1] - elif "__a21o_" in model: - result = (args[0] & args[1]) | args[2] - else: - self.fail(f"Unknown Boolean model: {model}") + for model, output, output_pin, inputs in ROWS: + self.assertIn(model, CELLS, f"Unknown Boolean model: {model}") + _, pin, function = CELLS[model] + self.assertEqual(output_pin, pin) self.assertNotIn(output, values) - values[output] = result + values[output] = function(**{name: values[key] for name, key in inputs.items()}) self.assertEqual([values[f"x{i}"] for i in range(5)], expected, bits) def test_actual_edit_keeps_boundary_objects_and_wires_every_pin(self): @@ -109,13 +120,23 @@ def test_actual_edit_keeps_boundary_objects_and_wires_every_pin(self): EDIT["edit"](top) self.assertTrue(all(gate.deleted for gate in originals)) live = [gate for gate in top.gates.values() if not gate.deleted] - self.assertEqual(len(live), 31) + self.assertEqual(len(live), 23) self.assertTrue(all(pin.net is not None for gate in live for pin in gate.pins.values())) for i, output in enumerate(outputs): self.assertIs(top.side_loads[i].net, output) - drivers = [gate for gate in live if gate.get_term("X").net is output] + drivers = [gate for gate in live if gate.get_term(CELLS[gate.model][1]).net is output] self.assertEqual(len(drivers), 1) + def test_a_row_cannot_read_a_term_before_it_is_driven(self): + # x0 is an original net: it exists from the start, but its new driver comes with its row. + source = ast.unparse(FUNCTIONS).replace("{'A1': 'p0', 'A2': 'c0', 'B1': 'g0'}", "{'A1': 'p0', 'A2': 'x0', 'B1': 'g0'}") + broken = {} + exec(compile(source, "edit.py", "exec"), broken) + top = Top() + with self.assertRaisesRegex(AssertionError, "read before it is driven"): + broken["edit"](top) + self.assertEqual(len(top.gates), 5) + def test_broken_chain_is_rejected_before_mutation(self): top = Top() top.gates["_217_"].pins["C"].net = object() @@ -124,12 +145,26 @@ def test_broken_chain_is_rejected_before_mutation(self): self.assertEqual(len(top.gates), 5) self.assertFalse(any(gate.deleted for gate in top.gates.values())) - def test_name_collision_is_rejected_before_mutation(self): + def test_new_gates_and_nets_never_share_a_name(self): top = Top() - top.nets["ppa_cla_g44"] = object() - with self.assertRaises(AssertionError): - EDIT["edit"](top) - self.assertEqual(len(top.gates), 5) + before = set(top.nets) + EDIT["edit"](top) + created = set(top.nets) - before + # 23 gates drive the 5 original boundary nets and 18 new ones. + self.assertEqual(len(created), 18) + self.assertFalse(created & set(top.gates)) + + def test_name_collision_is_rejected_before_mutation(self): + # One Verilog name space: a new name must be unused by nets, instances and ports alike. + for kind in ("nets", "gates", "ports"): + for name in ("ppa_cla_nG41", "ppa_cla_nG41_net", "ppa_cla_x4"): + top = Top() + getattr(top, kind)[name] = object() + with self.subTest(kind=kind, name=name): + with self.assertRaises(AssertionError): + EDIT["edit"](top) + self.assertEqual(len(top.gates), 5 + (kind == "gates")) + self.assertEqual(len(top.nets), 16 + (kind == "nets")) def test_missing_target_rejected(self): top = Top() diff --git a/tests/test_gcd_reference_regression.py b/tests/test_gcd_reference_regression.py index 1cbfc34..02446c7 100644 --- a/tests/test_gcd_reference_regression.py +++ b/tests/test_gcd_reference_regression.py @@ -171,6 +171,17 @@ def test_incomplete_routing_and_drc_errors_fail(self): with self.assertRaises(ValueError): REPLAY.physical_summary(self.work) + def test_parasitics_that_were_not_annotated_fail(self): + self.physical_fixture() + with (self.work / "tool.log").open("a") as log: + log.write("[WARNING DRT-0349] LEF58_ENCLOSURE with no CUTCLASS is not supported.\n") + REPLAY.physical_summary(self.work) + # What an instance named like a net causes: its wires are missing from the timing. + with (self.work / "tool.log").open("a") as log: + log.write("[WARNING STA-1652] /flow/results/gcd.spef line 11906, pin ppa_cla_p4 not found.\n") + with self.assertRaisesRegex(ValueError, "1 parasitics were not annotated"): + REPLAY.physical_summary(self.work) + def test_clean_electrical_report_may_be_empty_but_must_exist(self): self.physical_fixture() path = self.work / "reports/electrical.rpt" @@ -323,6 +334,34 @@ def test_stage_cannot_skip_formal_proof(self): REPLAY.stage("candidate", self.work, self.work / "fixture", 10) run.assert_not_called() + def test_edit_stage_checks_names_in_the_exported_candidate(self): + fixture = self.work / "fixture" + for names_ok in (False, True): + (self.work / "metadata.json").write_text(json.dumps( + {"completed": ["prepare", "baseline", "inspect"], "fixture": str(fixture)})) + commands = [] + + def run(directory, command, **kwargs): + commands.append([str(item) for item in command]) + if len(commands) == 1: + (self.work / "candidate.v").write_text("module gcd(); endmodule\n") + elif not names_ok: + raise RuntimeError("Tool exited 1") + + with self.subTest(names_ok=names_ok), patch.object(REPLAY, "validate_inputs"), \ + patch.object(REPLAY, "run_command", side_effect=run), patch("builtins.print"): + if names_ok: + REPLAY.stage("edit", self.work, fixture, 10) + else: + with self.assertRaises(RuntimeError): + REPLAY.stage("edit", self.work, fixture, 10) + self.assertEqual(commands[0][1], str(REPLAY.REFERENCE / "edit.py")) + self.assertEqual(commands[1][1:], [ + str(ROOT / "tools/edit_validation.py"), "--liberty", + str(fixture / "test/sky130hd/sky130hd_tt.lib"), "--verilog", str(self.work / "candidate.v")]) + completed = json.loads((self.work / "metadata.json").read_text())["completed"] + self.assertEqual("edit" in completed, names_ok) + def test_changed_candidate_after_proof_is_rejected(self): inputs = self.work / "inputs" inputs.mkdir() @@ -377,7 +416,7 @@ def test_model_context_excludes_reference_answer(self): self.assertTrue((example / "reference/historical-results.json").is_file()) task = (example / "task.md").read_text() self.assertIn("flow/backend/SKILL.md", task) - for leaked in ("_215_", "_219_", "generate/propagate", "prefix", "31-gate", "0.5998"): + for leaked in ("_215_", "_219_", "generate/propagate", "prefix", "31-gate", "23-gate", "0.5998"): self.assertNotIn(leaked, task) diff --git a/tests/test_live_session.py b/tests/test_live_session.py index 414583f..811a659 100644 --- a/tests/test_live_session.py +++ b/tests/test_live_session.py @@ -11,13 +11,25 @@ from unittest.mock import Mock, patch from tools import live_session as live -from tools.edit_validation import editing_function, validate_script +from tools.edit_validation import editing_function, explain_shared_names, shared_names, validate_script from test_gcd_reference_regression import proof_result GOLDEN_REF = dict(session_id="fixture-session", db_id=2, library_id=1, design_id=0) CANDIDATE_REF = dict(session_id="fixture-session", db_id=1, library_id=1, design_id=0) +def design(name, model=None, instances=(), nets=(), ports=()): + """A design, or an instance of one, with only what the name check reads.""" + item = Mock() + item.get_name.return_value = name + item.get_model_name.return_value = model or name + item.get_child_instances.return_value = list(instances) + item.get_nets.return_value = [Mock(**{"get_name.return_value": net}) for net in nets] + item.get_terms.return_value = [Mock(**{"get_name.return_value": port}) for port in ports] + item.is_leaf.return_value = not instances + return item + + def attached_result(status="equivalent", proven=18): result = proof_result(status, proven=proven) result.update(report_format="structured-v1", report_id="proof-identity", @@ -59,6 +71,29 @@ def test_bad_syntax_and_oversized_script(self): with self.assertRaises(ValueError): validate_script(" " * (1024 * 1024 + 1)) + def test_shared_names_are_instances_named_like_a_net_or_port(self): + gates = [design(name, "BUF") for name in ("g", "n1", "a", "")] + top = design("top", instances=gates, nets=["a", "n1", "n2", ""], ports=["a", "clk"]) + self.assertEqual(shared_names(top), {("top", "n1"), ("top", "a")}) + # A port and its net have one name in every design: that is not a clash. + clean = design("top", instances=[design("g", "BUF")], nets=["a"], ports=["a"]) + self.assertEqual(shared_names(clean), set()) + + def test_shared_names_cover_each_lower_module_once(self): + def block(instance): + return design(instance, "block", instances=[design("x", "BUF")], nets=["x"]) + first, second = block("u1"), block("u2") + found = shared_names(design("top", instances=[first, second], nets=["w"])) + self.assertEqual(found, {("block", "x")}) + self.assertEqual(first.get_nets.call_count + second.get_nets.call_count, 1) + self.assertIn("x (module block)", explain_shared_names(found)) + self.assertIn("and 3 more", explain_shared_names({("top", f"n{index}") for index in range(11)})) + + def test_a_shared_name_can_be_repaired_by_renaming(self): + top = Mock() + editing_function('def edit(top):\n top.get_net("g").set_name("g_net")\n')(top) + top.get_net.return_value.set_name.assert_called_once_with("g_net") + class SessionTests(unittest.TestCase): def setUp(self): @@ -91,10 +126,15 @@ def setUp(self): session._liberty_paths = [library] session._source_hashes = {str(library): hashlib.sha256(library.read_bytes()).hexdigest()} session._inspections = {} + session._accepted_names = set() self.session = session fingerprint = patch.object(live, "_fingerprint", side_effect=lambda design: design.signature) fingerprint.start() self.addCleanup(fingerprint.stop) + self.shared = set() + names = patch.object(live, "shared_names", side_effect=lambda top: set(self.shared)) + names.start() + self.addCleanup(names.stop) def test_agent_attachment_is_a_copy_without_secrets_or_side_effects(self): self.session._bridge.connection_file.write_text('{"token": "never-return-this"}') @@ -169,6 +209,36 @@ def edit(top): self.assertEqual(self.session.status()["state"], "edit_error") self.session._client.call.assert_not_called() + def test_edit_adding_a_shared_name_is_an_error_until_renamed(self): + self.session.proof = {"status": "proved"} + + def clash(top): + self.shared.add(("fixture", "g")) + top.signature += "-clash" + + def unrelated(top): + top.signature += "-more" + + def rename(top): + self.shared.clear() + top.signature += "-renamed" + + for edit in (clash, unrelated): + with patch.object(live, "editing_function", return_value=edit), \ + self.assertRaisesRegex(ValueError, r"g \(module fixture\)"): + self.session.apply_edit("edit script") + self.assertEqual(self.session.status()["state"], "edit_error") + self.assertIsNone(self.session.proof) + self.session._client.call.assert_not_called() + with patch.object(live, "editing_function", return_value=rename): + self.assertEqual(self.session.apply_edit("edit script")["status"], "proved") + self.assertEqual(self.session._candidate.signature, "candidate-clash-more-renamed") + + def test_names_the_loaded_design_shares_are_not_edit_errors(self): + self.session._accepted_names = {("fixture", "old")} + self.shared.add(("fixture", "old")) + self.assertEqual(self.session.apply_edit("def edit(top):\n pass")["status"], "proved") + def test_invalid_script_never_mutates_or_discards_valid_proof(self): self.session.proof = {"status": "proved"} with self.assertRaises(ValueError): diff --git a/tools/edit_validation.py b/tools/edit_validation.py index badb3cb..5157611 100644 --- a/tools/edit_validation.py +++ b/tools/edit_validation.py @@ -14,7 +14,7 @@ "get_bits", "get_bit", "get_name", "get_model_name", "get_direction", "is_input", "is_output", "is_inout", "is_leaf", "is_sequential", "create_net", "create_child_instance", "connect_upper_net", "disconnect", - "delete", "rename", "get", "items", "keys", "values", "append", "extend", + "delete", "rename", "set_name", "get", "items", "keys", "values", "append", "extend", "add", "update", "pop", "copy", "index", "count", }) @@ -61,3 +61,61 @@ def editing_function(source): namespace = {"__builtins__": dict(BUILTINS)} exec(code, namespace) return namespace["edit"] + + +def shared_names(top): + """(module, name) for each instance named like a net or port of its module. + + Verilog keeps a module's instances, nets and ports in one name space. + NajaEDA keeps them apart: it creates such a pair and exports it, and its + own reader, Kepler Formal and OpenROAD accept the file, so neither SEC nor + the physical flow fails. Strict readers such as Verilator and Yosys reject + it, and OpenROAD loses the extracted parasitics of those nets. + """ + found, seen, pending = set(), set(), [top] + while pending: + design = pending.pop() + module = design.get_model_name() + if module in seen: + continue + seen.add(module) + children = list(design.get_child_instances()) + taken = {item.get_name() for item in (*design.get_nets(), *design.get_terms())} - {""} + found.update((module, name) for name in (child.get_name() for child in children) if name in taken) + pending.extend(child for child in children if not child.is_leaf()) + return found + + +def explain_shared_names(names): + listed = sorted(names) + text = ", ".join(f"{name} (module {module})" for module, name in listed[:8]) + if len(listed) > 8: + text += f" and {len(listed) - 8} more" + return ("An instance has the name of a net or port of its module, which Verilog " + f"does not allow: {text}. Rename one of each pair with set_name") + + +def main(): + """Check an exported netlist, reloaded from the file as the flow's tools read it.""" + import argparse + + parser = argparse.ArgumentParser( + description="Fail if an instance of the netlist has the name of a net or port of its module.") + parser.add_argument("--liberty", required=True, nargs="+") + parser.add_argument("--verilog", required=True) + args = parser.parse_args() + from najaeda import netlist + + netlist.reset() + netlist.load_liberty(args.liberty) + top = netlist.load_verilog([args.verilog]) + if top is None: + parser.exit(1, "Name check failed: no top loaded\n") + found = shared_names(top) + if found: + parser.exit(1, f"Name check failed: {explain_shared_names(found)}\n") + print("NAMES_OK: no instance has the name of a net or port") + + +if __name__ == "__main__": + main() diff --git a/tools/live-session.md b/tools/live-session.md index b8b5401..59658ec 100644 --- a/tools/live-session.md +++ b/tools/live-session.md @@ -122,13 +122,18 @@ still perform no exports. Inspection of a rejected candidate is diagnostic only. | `proved` | Full SEC proof for the current cumulative revision | | `unproven` | Partial/inconclusive proof with actual coverage; warning, not equivalence | | `rejected` | Counterexample or verification error; no valid proof | -| `edit_error` | Script raised; partial candidate changes remain, no valid proof | +| `edit_error` | Script raised or left an instance named like a net or port; partial candidate changes remain, no valid proof | | `verification_pending` | Timed-out verification may still be running; no edits allowed | | `invalid` | Golden/untracked candidate/universe changed; stop this session | A rejected script that never executes leaves the existing revision and proof intact. An execution error or counterexample does not roll back the candidate: inspect the error and repair that same cumulative candidate through `apply_edit`. +An edit that gives an instance the name of a net or port of its module, or the +reverse, is such an error: Verilog has one name space per module, so the later +export would not be valid. SEC is not run; rename one of the pair with +`set_name` in the next edit. Names the loaded design already shared are not +reported. After a verification timeout, wait until the native call is idle and explicitly call `session.verify()` before editing again. Never treat a timeout as a warning proof. Do not forcibly destroy designs while native verification is running. diff --git a/tools/live_session.py b/tools/live_session.py index 7d0c2d7..0920009 100644 --- a/tools/live_session.py +++ b/tools/live_session.py @@ -13,7 +13,7 @@ import tempfile import threading -from tools.edit_validation import editing_function +from tools.edit_validation import editing_function, explain_shared_names, shared_names ROOT = Path(__file__).resolve().parents[1] @@ -180,6 +180,8 @@ def __init__(self, reference, liberty_files, work_dir, *, timeout=600, self._universe.setTopDesign(self._candidate) self._golden_hash = _fingerprint(self._golden) self._candidate_hash = _fingerprint(self._candidate) + # Names the loaded design already shares are its own; an edit may add none. + self._accepted_names = shared_names(netlist.get_top()) self._bridge = SessionBridge(output_dir=self.directory / "formal").start() self._golden_ref = self._bridge.design_reference(self._golden) self._candidate_ref = self._bridge.design_reference(self._candidate) @@ -377,7 +379,12 @@ def apply_edit(self, script): with self._bridge.lock: self._universe.setTopDesign(self._candidate) try: - function(self._netlist.get_top()) + top = self._netlist.get_top() + function(top) + # NajaEDA allows it; the Verilog exported later would not be valid. + added = shared_names(top) - self._accepted_names + if added: + raise ValueError(explain_shared_names(added)) finally: self._candidate_hash = _fingerprint(self._candidate) self._check() diff --git a/tools/najaeda/SKILL.md b/tools/najaeda/SKILL.md index 02f5323..66918c3 100644 --- a/tools/najaeda/SKILL.md +++ b/tools/najaeda/SKILL.md @@ -39,6 +39,20 @@ run [Kepler SEC](../kepler-formal/SKILL.md); cell-count changes are diagnostics, not a correctness proof. Detect internal-net/port naming collisions when signals have been disconnected; Verilog names in one module can re-alias separate objects. +Never give an instance the name of a net or port of the same module, or the +reverse. Verilog keeps all three in one name space; NajaEDA keeps them apart, +so it creates and exports such a pair without complaint. NajaEDA, Kepler Formal +and OpenROAD read that file back, so SEC and the physical flow still pass. +The file is not valid Verilog, though: strict readers such as Verilator and +Yosys reject it, and OpenROAD loses the extracted parasitics of those nets and +reports better timing than the layout has. A persistent session refuses an +edit that adds such a pair. In the file-based flow, check every exported +candidate before SEC: + +```sh +python tools/edit_validation.py --liberty /absolute/cells.lib --verilog /absolute/candidate.v +``` + The [GCD reference script](../../examples/backend/gcd/reference/edit.py) is a design-specific worked solution, not a generic optimization pass. Read it only for explicit replay or comparison, not when solving the GCD task independently. diff --git a/tools/najaeda/gate-replacement.md b/tools/najaeda/gate-replacement.md index 3b1d9d5..89de385 100644 --- a/tools/najaeda/gate-replacement.md +++ b/tools/najaeda/gate-replacement.md @@ -8,7 +8,12 @@ Purpose: local structural replacement. This is not a constant-propagation helper 2. Capture boundary **net objects**, not guessed names, from `instance.get_term(pin).get_upper_net()`. Capture all output nets, including intermediate outputs with consumers outside the replacement group. -3. Check every expected chain connection and make new net/instance names unique. +3. Check every expected chain connection. Use a new name only if + `top.get_net(name)`, `top.get_child_instance(name)` and `top.get_term(name)` + all return `None`, and never give a new net the name of a new instance: + Verilog keeps nets, instances and ports in one name space per module, which + NajaEDA does not enforce. Derive both names from one stem, for example + `` for a gate and `_net` for the net it drives. Validate the complete replacement specification before deleting anything. 4. Create internal nets with `top.create_net(name)` and gates with `top.create_child_instance(model=model_name, name=instance_name)`. diff --git a/tools/openroad/SKILL.md b/tools/openroad/SKILL.md index 41952d2..333cefc 100644 --- a/tools/openroad/SKILL.md +++ b/tools/openroad/SKILL.md @@ -23,6 +23,11 @@ TNS, area, estimated power and activity assumptions, electrical violations, routing status and DRC count. Save the final database, DEF, Verilog and SDC when the selected flow supports them. Do not treat pre-route timing as final timing. +After parasitic extraction, search the log for annotation warnings such as SPEF +pins or nets `not found`. Timing is then reported without those wires and looks +better than the layout is. Treat that run as failed and remove the cause, for +example an instance that has the name of a net ([NajaEDA](../najaeda/SKILL.md)). + When a visual explanation is requested, open the saved database with the matching technology data in OpenROAD's GUI. Show the full layout and a separately focused critical path. Capture actual tool output, not a synthetic drawing presented as