feat: ship compute_floorplan_shape + compute_slack_margin scripts

[oharboe]

Summary

Two ready-to-use Tcl scripts at the repo root for use with the existing orfs_arguments rule:

• compute_floorplan_shape.tcl — emits CORE_UTILIZATION and CORE_MARGIN from synth-stage ODB area, accounting for repair_design std-cell growth.
• compute_slack_margin.tcl — emits SETUP_SLACK_MARGIN and HOLD_SLACK_MARGIN from the previous stage's worst slack with a Δ safety budget that prevents the SLACK_MARGIN=0 futile-loop.

Both scripts parameterise their calibration constants via env vars (defaults documented in docs/orfs_arguments.md); per-design overrides via the arguments attr on orfs_arguments.

What's in the diff

• compute_floorplan_shape.tcl — new (~110 lines, mostly comments).
• compute_slack_margin.tcl — new (~85 lines).
• Both exposed from the root BUILD exports_files block alongside synth.tcl / mock_area.tcl.
• gallery/smoketest:counter adopts both scripts as a worked example. lint = False (real-yosys flow only) since the scripts use real OpenDB / OpenSTA queries; SYNTH_HDL_FRONTEND overridden to "" to avoid the slang plugin dependency.
• New default-set bazelisk test targets in smoketest:
  • :counter_computed_arguments_build_test — confirms the two orfs_arguments invocations build and emit JSON.
  • :counter_computed_arguments_test (py_test) — asserts the JSON outputs contain the expected ORFS variable keys with sensible values.
• docs/orfs_arguments.md — appends a use-case write-up: "A way out of parameter guess, pray, stare at logs hell". Frames the scripts as a mechanism for the upstream ORFS goal of "moving variables upwards in the Trivial / Easy / Complex taxonomy" (citing OpenROAD-flow-scripts/docs/user/FlowVariables.md), and discusses composition with AutoTuner / external DSE.
• README.md — one-paragraph cross-reference in the existing DSE section.

Why this is being proposed

The scripts have been validated on a production ASIC flow on ASAP7 across a range of core counts. In that context they replaced ~7 hand-tuned per-configuration constants and removed a recurring failure mode where SLACK_MARGIN=0 triggered hundreds of repair-timing passes and an ODB-1200 crash. Defaults shipped here are the values that worked for that flow; they should be treated as a starting point, not a universal truth.

Honest about the limits

• Defaults calibrated against one design family on one PDK. Portability is unproven.
• The flow is one-shot per build — no closed loop that re-runs after route to confirm density actually landed in band.
• PLACE_DENSITY (the marquee Easy variable in the upstream taxonomy) is not yet computed; that would be a natural follow-on.

Test plan

• bazelisk build //smoketest:counter_floorplan_shape //smoketest:counter_floorplan_slack (gallery) — green; emits JSON with the expected keys.
• bazelisk build //smoketest:counter_floorplan (gallery) — green; floorplan args.mk merges the computed values and synth/floorplan/PDN run cleanly (Design area 27 µm², 19% utilization on the counter).
• bazelisk test //smoketest:counter_computed_arguments_test //smoketest:counter_computed_arguments_build_test (gallery) — green.
• buildifier --mode=diff on modified BUILD files — clean.
• Full bazelisk test ... in gallery — not run by submitter; relying on PR CI for the gallery sweep.

🤖 Generated with Claude Code