Linting ORFS config.mk: Seconds Instead of Hours

[oharboe]

The Problem

You change PLACE_DENSITY in your config.mk. You run the flow. You wait 2 hours. It fails with a cryptic Make error because you also had a typo in ADDITIONAL_LEFS. You fix it. Another 2 hours. This time it fails because the SDC file path was wrong.

Every config.mk edit costs hours of wall-clock time before you find out if it's correct.

config.mk Is a DSL

If you look at config.mk files across ORFS designs, they all follow the same pattern: export a fixed set of variables (PLATFORM, DESIGN_NAME, VERILOG_FILES, SDC_FILE, CORE_UTILIZATION, ...) that control the flow. This isn't freeform Make — it's a domain-specific language for configuring chip builds. Recognizing this means we can parse it, validate it, and catch errors without running the actual flow.

What If You Could Know in Seconds?

I, with the help of Claude, built a linting flow that validates your entire config.mk — all stages, synthesis through final — in under 1 second per design. It catches:

• Missing verilog files
• Bad file paths (SDC, LEF, LIB, TCL)
• Unresolvable variable references
• Module hierarchy errors (missing submodules, port mismatches)
• Include directory problems

It does this by running the real ORFS Makefile and scripts with lightweight mock tools that create stub outputs instead of doing actual EDA processing.

RTLIL: Fast Precursor to Full Synthesis

The one step that does run for real is yosys RTLIL generation — a fast pass that reads all your verilog, resolves the module hierarchy, and writes out an intermediate representation. This takes seconds even for large designs, compared to hours for full synthesis with technology mapping and optimization. But it tells us almost everything we need: are all files found? do all modules exist? do port connections match? is the hierarchy complete?

Design	RTLIL generation	Full synthesis	Speedup
gcd	<1s	~2 min	>100x
ibex	~1s	~10 min	>600x
cva6	~5s	~2 hours	>1400x
swerv_wrapper	~13s	~4 hours	>1100x

After RTLIL, the remaining stages (floorplan through final) run with mock-openroad — a ~100 line Python stub that creates empty output files so Make thinks each stage completed. The whole flow, all stages, completes in seconds.

Results So Far

51 ORFS designs across 6 platforms (asap7, sky130hd, sky130hs, nangate45, ihp-sg13g2, gf180) all pass the linting flow. Total time: under 30 seconds for all 51 designs.

Along the way, the linting flow caught real bugs in ORFS configs that had been hiding because nobody runs the full flow on every design regularly:

• Missing fakeram verilog in VERILOG_FILES (riscv32i, swerv_wrapper)
• Verilog specify blocks that yosys can't parse (nangate45 fakeram .v)
• Port mismatches between uart modules (gf180/uart-blocks)
• Missing include directories for SystemVerilog headers (cva6, mempool_group)
• Unresolved cross-variable references (microwatt VERILOG_FILES_BLACKBOX)

How It Works

The linting flow uses bazel-orfs, which wraps the same ORFS Makefile and scripts you already use. Your config.mk stays exactly the same — no changes needed. A parser reads it and generates build targets automatically. For each design you get two sets of targets: the real flow (uses the Docker image, takes hours) and the lint flow (uses mock tools, takes seconds). You can run either without touching any files.

What's Next

Better Error Messages

Right now, errors come from yosys or Make — not always human-friendly. The mock tools can be extended to validate ORFS variables (is CORE_UTILIZATION in range? does the SDC clock name match a port?), check file existence upfront, and report clear diagnostics before the flow even starts.

Incremental Caching

Because each stage is a separate build target, changing PLACE_DENSITY only rebuilds placement and later stages — synthesis is cached. This works for both real and lint flows.

Flow Rules Check (FRC)

Think of this like Design Rule Check but for flow configuration. Each check is a unit test against the mock tools. Over time we build up a library of checks:

• Variable range validation (CORE_UTILIZATION 0-100)
• SDC sanity (clock period vs technology)
• LEF/LIB consistency (all referenced macros have both)
• Timing constraint completeness

Interested in Trying This?

I'm keeping this work in bazel-orfs for now rather than sending patches to ORFS directly. The ORFS changes needed (config.mk parser, BUILD files, some config.mk fixes) are maintained as patches inside bazel-orfs. This has a couple of advantages:

• Less churn on ORFS. The patches can mature and stabilize before they land. No half-baked PRs cluttering the ORFS repo.
• Easy to try. You just check out origin/main of bazel-orfs — it pulls in ORFS and applies the patches automatically. No need to maintain a custom ORFS fork or juggle branches.
• CI catches regressions. bazel-orfs CI runs the full lint flow against all ORFS designs on every pull request. If a mock tool change breaks a design, we know immediately.

Once the linting flow is stable and the ORFS patches are minimal and well-tested, I'll file them as individual PRs to ORFS.

Thoughts? Questions?

• What config.mk errors bite you most often?
• What checks would save you the most time?
• Are there designs where the linting flow would be especially valuable?
• Would you find this useful for your workflow?

[oharboe]

@MrAMS FYI

[Blueonics]

This is cool! I'd be interested to try it out.

[oharboe]

You can start by reading a bit on https://github.com/The-OpenROAD-Project/bazel-orfs, I need to wrap up what I have and write a blurb in a pull request and get it merged.

[maliberty]

It sounds useful.

[oharboe]

It's what you wanted to do a long time back, you started a mock openroad. But it wasn't economic to write the mock openroad/yosys + a tcl interpreter good 'nuf to drive the flow and invert the whole testing problem...