Timing report HTML generation (integration demo)

[oharboe]

Summary

No more click and wait in timing reports. Run a build overnight and get histogram and timing reports in seconds without having to load timing information.

This is the first demo of a grander vision of static HTML GUI and the Qt GUI being a developer tool and the single source of truth for the HTML GUI.

Self-contained HTML timing reports generated from any ORFS stage, matching the OpenROAD Qt GUI (Charts + Timing Report widgets) as closely as possible without modifying src/sta.

This is an integration demo. Individual features and bug fixes will be broken out into separate PRs. This branch will be force-rebased on top of those changes as they land, serving as a living status report.

Usage

cd tools/OpenROAD

# Build timing report for any ORFS stage
bazelisk build //test/orfs/gcd:gcd_synth_timing
bazelisk build //test/orfs/mock-array:MockArray_4x4_base_synth_timing

# Open in browser
bazelisk run //test/orfs/gcd:gcd_synth_timing
bazelisk run //test/orfs/mock-array:MockArray_4x4_base_synth_timing

Adding timing reports to any ORFS design is one line in BUILD:

load("//test/orfs:timing.bzl", "orfs_timing_stages")

orfs_timing_stages(
    name = "gcd",
    stages = ["synth", "floorplan", "place", "cts", "grt", "route"],
    timing_script = "//etc:timing_report",
)

What it produces

A single self-contained HTML file (~300KB for MockArray) with:

• Endpoint Slack Histogram — nice-bucket algorithm ported from chartsWidget.cpp, red/green bars, dropdowns for path group and clock filtering
• Timing Report table — columns match Qt TimingPathsModel: Capture Clock, Required, Arrival, Slack, Skew, Logic Delay, Logic Depth, Fanout, Start, End (all in ps)
• Data Path Details — per-arc Pin, Fanout, ↑/↓, Time, Delay, Slew, Load (matching TimingPathDetailModel)
• Unconstrained pin count below histogram
• Draggable sashes between panels

Known Issues

STA search state crash (blocker for C++ extension points)

The C++ Timing::getTimingPaths(), getClockInfo(), and getSlackHistogram() abort when called from the Bazel Python API. The root cause is that STA's internal search state is left in a condition where subsequent calls crash. ensureGraph() + searchPreamble() don't help.

Workaround: timing paths extracted via Tcl report_checks -format json. Histogram bucketing done in JS.

Fix needed: changes to src/sta to properly reset search state between Python API calls.

Histogram buckets differ slightly from Qt

The JS snapInterval algorithm matches chartsWidget.cpp but unconstrained endpoint filtering differs slightly.

See docs/timing_report_todo.md for the full Qt GUI discrepancy list.

An .md file for pull requests?

There's also an .md file with information that could be used in a pull request, but that's a little bit off topic, but here is what it looks like currently. Perhaps drop this and focus on .html in this PR.

PASS Timing — MockArray — asap7 | Setup WNS 0.0000 ns TNS 0.0000 ns | Hold WNS 0.0000 ns

	Setup	Hold
WNS	0.0000 ns	0.0000 ns
TNS	0.0000 ns	0.0000 ns
Endpoints	5172	—

Slack distribution (setup):
                     █    ▃     ▃         ▂▆   2120 endpoints
    0.000                            0.000 ns

Clock Domains

Clock	Period (ns)	Sources
clock	250.0	``

Cell Type Breakdown (top 10 by delay)

Cell	Count	Total Delay (ns)	Avg Slew (ns)
MockArray	200	0.0000	0.0000

Full interactive report: see 1_timing.html artifact

Test plan

• bazelisk build //test/orfs/gcd:gcd_synth_timing passes
• bazelisk build //test/orfs/mock-array:MockArray_4x4_base_synth_timing passes
• bazelisk run opens HTML in browser with histogram + path table + detail
• Path group dropdown shows all groups (including empty ones)
• Clicking histogram bar filters path table
• Screenshots match Qt GUI layout

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces an impressive feature for generating self-contained HTML timing reports. The implementation is comprehensive, covering C++ API extensions, Python scripting for report generation, and Bazel rules for integration. My review focuses on improving the correctness of the generated reports, enhancing robustness, and increasing maintainability. I've identified a few areas for improvement, including the calculation of logic delay, error handling, and configuration management.

[gemini-code-assist]

Catching a generic Exception can hide unexpected errors and make debugging more difficult. It's better to catch specific exceptions that you expect to handle, such as json.JSONDecodeError if the file content is not valid JSON, or IOError for file-related issues.

Suggested change

	except Exception:
	return []
	except json.JSONDecodeError as e:
	print(f"[timing_report] ERROR: Failed to parse JSON from report_checks output: {e}", file=sys.stderr)
	return []

[gemini-code-assist]

The logic_delay for each path is not being calculated, causing the report to incorrectly display the arrival time instead. You can calculate logic_delay here by summing the delays of the non-net arcs in the path.

After this change, you should also update line 524 in the Javascript template from <td>${{ps(p.logic_delay || p.arrival)}}</td> to <td>${{ps(p.logic_delay)}}</td> to ensure the correct value is displayed.

Suggested change

	# Compute logic depth
	cells = set()
	for a in p["arcs"]:
	if not a["net"] and a["cell"]:
	cells.add(a["to"])
	p["logic_depth"] = len(cells)
	# Compute logic depth and logic delay
	cells = set()
	logic_delay = 0.0
	for a in p["arcs"]:
	if not a["net"] and a["cell"]:
	cells.add(a["to"])
	logic_delay += a["delay"]
	p["logic_depth"] = len(cells)
	p["logic_delay"] = logic_delay

[gemini-code-assist]

If the LIB_FILES environment variable is not set or is an empty string, os.environ.get("LIB_FILES", "").split() will result in a list containing an empty string ['']. This could cause issues later when trying to read the liberty file. It's safer to handle the case of an empty string explicitly.

Suggested change

	lib_files = os.environ.get("LIB_FILES", "").split()
	lib_files_str = os.environ.get("LIB_FILES", "")
	lib_files = lib_files_str.split() if lib_files_str else []

[gemini-code-assist]

The current implementation of logic_delay_total includes delays from all instance arcs that are not on a clock path. However, the standard definition of logic delay typically excludes buffers and inverters. To improve accuracy, consider checking if the instance is a buffer or inverter and excluding its delay from logic_delay_total.

You could use design_->getResizer()->isBuffer(lib_cell) and is_inverter for this check, which would require including rsz/Resizer.hh.

[gemini-code-assist]

Hardcoding the filter for liberty files based on "NLDM" and "_FF_" in the path is brittle and may not work for all PDKs or corners. As noted in your documentation, this should be improved. A more robust solution would be to propagate the correct list of library files from the orfs_flow rule, possibly through a custom provider, rather than relying on string matching within this rule.

[github-actions]

clang-tidy made some suggestions

[github-actions]

warning: use emplace_back instead of push_back [modernize-use-emplace]

Suggested change

	info.sources.push_back(network->pathName(pin));
	info.sources.emplace_back(network->pathName(pin));

[github-actions]

warning: no header providing "sta::StringSeq" is directly included [misc-include-cleaner]

src/Timing.cc:35:

- #include "sta/TimingArc.hh"
+ #include "sta/StringUtil.hh"
+ #include "sta/TimingArc.hh"

[github-actions]

warning: no header providing "sta::PathEndSeq" is directly included [misc-include-cleaner]

src/Timing.cc:35:

- #include "sta/TimingArc.hh"
+ #include "sta/SearchClass.hh"
+ #include "sta/TimingArc.hh"

[github-actions]

warning: no header providing "sta::Path" is directly included [misc-include-cleaner]

src/Timing.cc:27:

- #include "sta/PathEnd.hh"
+ #include "sta/Path.hh"
+ #include "sta/PathEnd.hh"

[github-actions]

warning: use std::max instead of > [readability-use-std-min-max]

Suggested change

	}
	max_fanout = std::max(node_fanout, max_fanout);