Tool-Native Tcl vs Python-Owned Flow Logic

THOUGHTS = [
    ("I generate the Tcl, so I know what the design contains",
     "no — the spec is the input, not the design"),
    ("get_cells is just a pattern match over instance names",
     "it is a query against an elaborated hierarchy — §3"),
    ("I could parse the netlist and skip the tool",
     "measured in §3: 1 against 8"),
    ("Python has better string handling than Tcl",
     "true, and irrelevant to this question"),
]

print(f"{'the thought':<52} the answer")
for t, a in THOUGHTS:
    print(f"{t:<52} {a}")

print()
print("thoughts that are true:", 1)
print("thoughts that are true AND relevant:", 0)

the thought                                          the answer
I generate the Tcl, so I know what the design contains no — the spec is the input, not the design
get_cells is just a pattern match over instance names it is a query against an elaborated hierarchy — §3
I could parse the netlist and skip the tool          measured in §3: 1 against 8
Python has better string handling than Tcl           true, and irrelevant to this question

thoughts that are true: 1
thoughts that are true AND relevant: 0

# inside the tool: get_cells, report_timing, set_clock_groups
# outside: which corners to run, and what to do with the reports

INSIDE = ["get_cells", "report_timing", "set_clock_groups"]
OUTSIDE = ["which corners to run", "what to do with the reports"]

print("inside the tool:")
for c in INSIDE:
    print(f"  {c}")
print("outside:")
for c in OUTSIDE:
    print(f"  {c}")

print()
print("items the annotation places:", len(INSIDE) + len(OUTSIDE))
print("the reason it gives       :", "none")

inside the tool:
  get_cells
  report_timing
  set_clock_groups
outside:
  which corners to run
  what to do with the reports

items the annotation places: 5
the reason it gives       : none

import re
import subprocess
from pathlib import Path

NETLIST = """module leaf #(parameter ID = 0) (input a, output b);
  assign b = ~a;
  initial $display("  elaborated leaf ID=%0d", ID);
endmodule

module top #(parameter N = 8) (input [7:0] a, output [7:0] b);
  genvar i;
  generate
    for (i = 0; i < N; i = i + 1) begin : bank
      leaf #(.ID(i)) u_leaf (.a(a[i]), .b(b[i]));
    end
  endgenerate
  // leaf u_commented (.a(a[0]), .b(b[0]));
`ifdef EXTRA_LEAF
  leaf #(.ID(99)) u_ifdef (.a(a[0]), .b());
`endif
endmodule

module tb;
  reg [7:0] a = 8'h00; wire [7:0] b;
  top #(8) u_top(.a(a), .b(b));
  initial begin #1 $finish; end
endmodule
"""
Path("net.v").write_text(NETLIST, encoding="utf-8")

CELL = re.compile(r"^\s*(\w+)\s*(?:#\([^)]*\))?\s*(\w+)\s*\(", re.M)
SKIP = {"module", "generate", "for", "initial", "if"}

src = Path("net.v").read_text(encoding="utf-8")
found = [(m.group(1), m.group(2)) for m in CELL.finditer(src)
         if m.group(1) not in SKIP]

print("what a regex over the source finds:")
for mod, inst in found:
    print(f"  {mod:<8} {inst}")
print("  count:", len(found))

what a regex over the source finds:
  top      u_top
  count: 1

import subprocess
from pathlib import Path

NETLIST = """module leaf #(parameter ID = 0) (input a, output b);
  assign b = ~a;
  initial $display("  elaborated leaf ID=%0d", ID);
endmodule

module top #(parameter N = 8) (input [7:0] a, output [7:0] b);
  genvar i;
  generate
    for (i = 0; i < N; i = i + 1) begin : bank
      leaf #(.ID(i)) u_leaf (.a(a[i]), .b(b[i]));
    end
  endgenerate
  // leaf u_commented (.a(a[0]), .b(b[0]));
`ifdef EXTRA_LEAF
  leaf #(.ID(99)) u_ifdef (.a(a[0]), .b());
`endif
endmodule

module tb;
  reg [7:0] a = 8'h00; wire [7:0] b;
  top #(8) u_top(.a(a), .b(b));
  initial begin #1 $finish; end
endmodule
"""
Path("net.v").write_text(NETLIST, encoding="utf-8")


def elaborate(defines=()):
    args = ["iverilog", "-g2005"] + [f"-D{d}" for d in defines] + \
           ["-o", "n.vvp", "net.v"]
    c = subprocess.run(args, stdout=subprocess.PIPE,
                       stderr=subprocess.STDOUT, text=True)
    if c.returncode:
        return None
    r = subprocess.run(["vvp", "n.vvp"], stdout=subprocess.PIPE,
                       stderr=subprocess.STDOUT, text=True)
    return [l for l in r.stdout.splitlines() if "elaborated leaf" in l]


plain = elaborate()
print("what the elaborator creates:")
for l in plain:
    print(l)
print("  count:", len(plain))

extra = elaborate(["EXTRA_LEAF"])
print()
print("with -DEXTRA_LEAF:", len(extra))
print("the regex's answer :", 1, "in both cases")

what the elaborator creates:
  elaborated leaf ID=0
  elaborated leaf ID=1
  elaborated leaf ID=2
  elaborated leaf ID=3
  elaborated leaf ID=4
  elaborated leaf ID=5
  elaborated leaf ID=6
  elaborated leaf ID=7
  count: 8

with -DEXTRA_LEAF: 9
the regex's answer : 1 in both cases

REASONS = [
    ("the generate loop", "8 instances from 1 line",
     "the count is a parameter, resolved at elaboration"),
    ("the commented instance", "regex may find it, design has none",
     "comments are not part of the design"),
    ("the `ifdef instance", "present or absent per define",
     "the preprocessor runs before elaboration"),
    ("the parameter override", "top #(8) could be #(64)",
     "the instantiation decides, not the module"),
]

print(f"{'why they differ':<26} {'effect':<36} because")
for what, effect, why in REASONS:
    print(f"{what:<26} {effect:<36} {why}")

print()
print("reasons:", len(REASONS))
print("reasons a better regex could fix:", 0)

why they differ            effect                               because
the generate loop          8 instances from 1 line              the count is a parameter, resolved at elaboration
the commented instance     regex may find it, design has none   comments are not part of the design
the `ifdef instance        present or absent per define         the preprocessor runs before elaboration
the parameter override     top #(8) could be #(64)              the instantiation decides, not the module

reasons: 4
reasons a better regex could fix: 0

INSIDE = [
    ("get_cells", "reads the database",
     "the answer is computed from the elaborated hierarchy"),
    ("report_timing", "computes over the database",
     "needs the timing graph, the libraries and the constraints"),
    ("set_clock_groups", "mutates tool state",
     "changes how every later command behaves"),
]

print(f"{'command':<20} {'kind':<26} why it cannot leave")
for cmd, kind, why in INSIDE:
    print(f"{cmd:<20} {kind:<26} {why}")

print()
print("kinds:", len({k for _, k, _ in INSIDE}))
print("the mutating one is special because:",
      "its effect is invisible in any file")

command              kind                       why it cannot leave
get_cells            reads the database         the answer is computed from the elaborated hierarchy
report_timing        computes over the database needs the timing graph, the libraries and the constraints
set_clock_groups     mutates tool state         changes how every later command behaves

kinds: 3
the mutating one is special because: its effect is invisible in any file

OUTSIDE = [
    ("decide which corners to run",
     "reads a spec file", "the tool has no reason to read it"),
    ("compare tonight's WNS with last night's",
     "needs a previous run", "the session has one design loaded"),
    ("decide pass or fail against a policy",
     "needs a threshold and a reason", "29.2's policy, not a tool concern"),
    ("fail before launching if a library is missing",
     "a pre-flight check", "21.7 — the tool cannot check before it starts"),
    ("retry a flaky step",
     "needs to outlive the session", "a crashed session cannot retry itself"),
]

print(f"{'work':<42} {'needs':<26} why not inside")
for what, needs, why in OUTSIDE:
    print(f"{what:<42} {needs:<26} {why}")

print()
print("items:", len(OUTSIDE))
print("items that need something the session does not have:", len(OUTSIDE))

work                                       needs                      why not inside
decide which corners to run                reads a spec file          the tool has no reason to read it
compare tonight's WNS with last night's    needs a previous run       the session has one design loaded
decide pass or fail against a policy       needs a threshold and a reason 29.2's policy, not a tool concern
fail before launching if a library is missing a pre-flight check         21.7 — the tool cannot check before it starts
retry a flaky step                         needs to outlive the session a crashed session cannot retry itself

items: 5
items that need something the session does not have: 5

STEPS = [
    ("read libraries", 4),
    ("elaborate", 12),
    ("compile", 180),
    ("optimise", 140),
    ("report", 6),
]

total = sum(m for _, m in STEPS)
print(f"{'step':<18} {'minutes':>8}  cumulative")
cum = 0
for name, m in STEPS:
    cum += m
    print(f"{name:<18} {m:>8}  {cum}")

print()
print("total session           :", total, "minutes")
print("a missing library is found at:", STEPS[0][1], "minutes — if checked first")
print("a bad corner name is found at:", cum, "minutes — if checked in the report step")
print("cost of checking late       :", cum - STEPS[0][1], "minutes of a licence")

step                minutes  cumulative
read libraries            4  4
elaborate                12  16
compile                 180  196
optimise                140  336
report                    6  342

total session           : 342 minutes
a missing library is found at: 4 minutes — if checked first
a bad corner name is found at: 342 minutes — if checked in the report step
cost of checking late       : 338 minutes of a licence

def where(inputs):
    """Decide where work belongs by what it reads."""
    db = "design database" in inputs
    ext = any(i in inputs for i in ("spec file", "previous run", "policy",
                                    "filesystem"))
    if db and ext:
        return "SPLIT — the query inside, the decision outside"
    if db:
        return "inside the tool"
    return "outside"


CASES = [
    ("get_cells -hier *reg*", {"design database"}),
    ("report_timing", {"design database"}),
    ("set_clock_groups", {"design database"}),
    ("which corners to run", {"spec file"}),
    ("is tonight worse than last night", {"previous run"}),
    ("pass or fail", {"policy"}),
    ("report timing for every clock in the design",
     {"design database", "spec file"}),
    ("check the libraries exist", {"filesystem"}),
]

print(f"{'work':<46} where")
for what, inputs in CASES:
    print(f"{what:<46} {where(inputs)}")

print()
print("cases decided by naming the input:", len(CASES))
print("cases needing judgement           :", 0)

work                                           where
get_cells -hier *reg*                          inside the tool
report_timing                                  inside the tool
set_clock_groups                               inside the tool
which corners to run                           outside
is tonight worse than last night               outside
pass or fail                                   outside
report timing for every clock in the design    SPLIT — the query inside, the decision outside
check the libraries exist                      outside

cases decided by naming the input: 8
cases needing judgement           : 0

print("the task: report timing for every clock in the design")
print()
STEPS = [
    (1, "inside", "get_clocks", "returns the clock names from the database"),
    (2, "inside", "write them to a file", "the only way they cross — 32.2 §4"),
    (3, "outside", "read the file", "Python now has the list"),
    (4, "outside", "apply the policy", "which clocks matter, in what order"),
    (5, "outside", "generate the next script", "32.4"),
    (6, "inside", "report_timing per clock", "back in the tool"),
]

print(f"{'step':>4} {'where':<9} {'what':<28} note")
for n, where, what, note in STEPS:
    print(f"{n:>4} {where:<9} {what:<28} {note}")

crossings = sum(1 for i in range(1, len(STEPS))
                if STEPS[i][1] != STEPS[i - 1][1])
print()
print("boundary crossings:", crossings)
print("the wrong design would be:", "steps 3 and 4 inside the tool")
print("why                      :", "untestable, and 32.2 §7's criterion")

the task: report timing for every clock in the design

step where     what                         note
   1 inside    get_clocks                   returns the clock names from the database
   2 inside    write them to a file         the only way they cross — 32.2 §4
   3 outside   read the file                Python now has the list
   4 outside   apply the policy             which clocks matter, in what order
   5 outside   generate the next script     32.4
   6 inside    report_timing per clock      back in the tool

boundary crossings: 2
the wrong design would be: steps 3 and 4 inside the tool
why                      : untestable, and 32.2 §7's criterion

OPTIONS = [
    ("two sessions, Python decides between",
     2, "testable, versioned, comparable", "one extra launch"),
    ("one session, Tcl decides",
     1, "faster", "policy untestable and unversioned"),
]

print(f"{'design':<38} {'launches':>9}  gains / costs")
for name, n, gain, cost in OPTIONS:
    print(f"{name:<38} {n:>9}  +{gain} / -{cost}")

print()
print("the trade is:", "one tool launch against a testable policy")
print("for a nightly flow that is:", "obviously worth it")

design                                  launches  gains / costs
two sessions, Python decides between           2  +testable, versioned, comparable / -one extra launch
one session, Tcl decides                       1  +faster / -policy untestable and unversioned

the trade is: one tool launch against a testable policy
for a nightly flow that is: obviously worth it

OFFERINGS = [
    ("a typed record of a parsed report", "yes", "28.1 — the tool emits text"),
    ("a comparison between two runs", "yes", "29.4, 28.5 — the tool sees one"),
    ("a policy with a threshold and a reason", "yes", "29.2"),
    ("retry, timeout and a run directory", "yes", "25.x, 26.x"),
    ("a reimplementation of get_cells", "no", "§3"),
    ("a reimplementation of report_timing", "no", "§3"),
    ("a Python API that wraps the tool's Tcl", "sometimes",
     "useful as a thin shim; dangerous as an abstraction"),
]

print(f"{'what Python offers':<42} {'worth it':<11} reference")
for what, worth, ref in OFFERINGS:
    print(f"{what:<42} {worth:<11} {ref}")

yes = [o for o in OFFERINGS if o[1] == "yes"]
print()
print("clear yes:", len(yes))
print("clear no :", sum(1 for o in OFFERINGS if o[1] == "no"))
print("every yes has one thing in common:",
      "its input is not the design database")

what Python offers                         worth it    reference
a typed record of a parsed report          yes         28.1 — the tool emits text
a comparison between two runs              yes         29.4, 28.5 — the tool sees one
a policy with a threshold and a reason     yes         29.2
retry, timeout and a run directory         yes         25.x, 26.x
a reimplementation of get_cells            no          §3
a reimplementation of report_timing        no          §3
a Python API that wraps the tool's Tcl     sometimes   useful as a thin shim; dangerous as an abstraction

clear yes: 4
clear no : 2
every yes has one thing in common: its input is not the design database

LEVELS = [
    ("does it parse as Tcl?", "tclsh, no tool", "yes — §9"),
    ("are the values escaped correctly?", "tclsh, no tool", "yes — 32.4 §5"),
    ("is the command sequence the one the spec implies?",
     "a structural check", "yes"),
    ("does set_clock_groups accept these arguments?", "needs the tool", "no"),
    ("does report_timing find the path?", "needs the design", "no"),
]

print(f"{'question':<48} {'needs':<20} testable here")
for q, needs, ok in LEVELS:
    print(f"{q:<48} {needs:<20} {ok}")

print()
print("questions answerable without a licence:", 3)
print("questions needing the tool            :", 2)

question                                         needs                testable here
does it parse as Tcl?                            tclsh, no tool       yes — §9
are the values escaped correctly?                tclsh, no tool       yes — 32.4 §5
is the command sequence the one the spec implies? a structural check   yes
does set_clock_groups accept these arguments?    needs the tool       no
does report_timing find the path?                needs the design     no

questions answerable without a licence: 3
questions needing the tool            : 2

import subprocess
from pathlib import Path

GENERATED = """# GENERATED by gen_sta.py — do not edit
read_verilog /proj/rtl/top.v
create_clock -name clk -period 2.0 [get_ports clk]
set_clock_groups -asynchronous -group {clk} -group {jtag_tck}
report_timing -delay_type max -path_type full
"""
Path("run.tcl").write_text(GENERATED, encoding="utf-8")

STUBS = """proc read_verilog args { puts "STUB read_verilog $args" }
proc create_clock args { puts "STUB create_clock $args" }
proc get_ports args { return [list {*}$args] }
proc set_clock_groups args { puts "STUB set_clock_groups $args" }
proc report_timing args { puts "STUB report_timing $args" }
source run.tcl
"""
Path("harness.tcl").write_text(STUBS, encoding="utf-8")

r = subprocess.run(["tclsh", "harness.tcl"], stdout=subprocess.PIPE,
                   stderr=subprocess.STDOUT, text=True,
                   stdin=subprocess.DEVNULL)
print("returncode:", r.returncode)
for line in r.stdout.strip().splitlines():
    print("  ", line)

returncode: 0
   STUB read_verilog /proj/rtl/top.v
   STUB create_clock -name clk -period 2.0 clk
   STUB set_clock_groups -asynchronous -group clk -group jtag_tck
   STUB report_timing -delay_type max -path_type full

import re
import subprocess
from pathlib import Path

GENERATED = """read_verilog /proj/rtl/top.v
create_clock -name clk -period 2.0 [get_ports clk]
set_clock_groups -asynchronous -group {clk} -group {jtag_tck}
report_timing -delay_type max
"""
Path("run.tcl").write_text(GENERATED, encoding="utf-8")
Path("harness.tcl").write_text(
    "set ::calls [list]\n"
    "foreach c {read_verilog create_clock set_clock_groups report_timing} {\n"
    "  proc $c args \"lappend ::calls \\[list $c {*}\\$args\\]\"\n"
    "}\n"
    "proc get_ports args { return [list {*}$args] }\n"
    "source run.tcl\n"
    "foreach call $::calls { puts [lindex $call 0] }\n",
    encoding="utf-8")

r = subprocess.run(["tclsh", "harness.tcl"], stdout=subprocess.PIPE,
                   stderr=subprocess.STDOUT, text=True,
                   stdin=subprocess.DEVNULL)
order = r.stdout.strip().splitlines()
print("commands, in the order executed:")
for c in order:
    print("  ", c)

EXPECTED = ["read_verilog", "create_clock", "set_clock_groups", "report_timing"]
print()
print("expected order:", EXPECTED == order)
print("constraints before reporting:",
      order.index("create_clock") < order.index("report_timing"))
print("clock groups before reporting:",
      order.index("set_clock_groups") < order.index("report_timing"))

commands, in the order executed:
   read_verilog
   create_clock
   set_clock_groups
   report_timing

expected order: True
constraints before reporting: True
clock groups before reporting: True

import re
import subprocess
from pathlib import Path

SRC = """module leaf(input a, output b); assign b = ~a; endmodule
module top #(parameter N = 4) (input [3:0] a, output [3:0] b);
  genvar i;
  generate for (i = 0; i < N; i = i + 1) begin : bk
    leaf u (.a(a[i]), .b(b[i]));
  end endgenerate
endmodule
module tb; reg [3:0] a = 0; wire [3:0] b; top #(4) t(.a(a), .b(b));
  initial begin #1 $display("ok"); $finish; end endmodule
"""
Path("p.v").write_text(SRC, encoding="utf-8")

# A
print("A:", len(re.findall(r"^\s*leaf\s+\w+\s*\(", SRC, re.M)))

# B
print("B:", SRC.count("genvar"), "genvar,", SRC.count("N = 4"), "parameter default")

# C
c = subprocess.run(["iverilog", "-g2005", "-o", "p.vvp", "p.v"],
                   stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
print("C:", c.returncode)

# D
print("D:", "design database" in {"design database"},
      "design database" in {"spec file"})

A: 1
B: 1 genvar, 1 parameter default
C: 0
D: True False