[ENG-2416] .stadb

[stanminlee]

Summary

Replace the old .libdb liberty-only cache with .stadb: a binary session
cache that restores a linked, constrained, timed OpenSTA session so
report_checks works immediately — without re-running liberty parse,
link_design, graph build/levelize, delay calc, or search.

On large industrial designs those cold steps can each take ~10–20 minutes.
.stadb is a derivable cache (version/ABI mismatch → regenerate), not a
long-lived archive.

Commands

write_sta_db [-no_compress] filename.stadb
read_sta_db filename.stadb

What is serialized (v1, single scene)

Section	Replaces	How restore works
Liberty	read_liberty	NLDM tables via LibertyBuilder; CCS dropped with warning 2741
Network	read_verilog + link_design	Public ConcreteNetwork::make* API only (no private list surgery); instance attrs including src / verilog_src
SDC	constraint Tcl	Tagged binary stream; reader replays public Sdc mutators
Graph	graph + levelize + dcalc	Dense ObjectId-order makeVertex/makeEdge; delays/slews + annotation bits; Levelize/Dcalc “already done” flags
Search	arrival/required search	ClkInfo/Tag pools, path arrays, Sim + validity flags

Parasitics section id is reserved but not written yet.

Restore order (important)

Cold STA is constrain-then-build. Restore intentionally does:

liberty → network → graph → sdc → search

SDC’s create_generated_clock path calls updateGeneratedClks → levelize →
ensureGraph(). If the graph is not already installed, that rebuilds it from
the network and defeats the cache. Installing a levelized graph first makes
that path a no-op.

Liveness

Restored sessions stay editable. Computed delay annotation bits are left
clear so replace_cell still triggers incremental delay calc; SDF bits
stay set. Regressions assert both “report matches cold” and “edit after
restore matches cold edit.”

Guarantees / guards

• Single scene only (scenes().size() != 1 → skip write)
• ABI guard from sizeof of critical types → automatic cache miss on layout drift
• Skip-proof counters (liberty_cells_parsed, graph_vertices_made,
  levelize_runs, dcalc_vertices_computed, search_vertices_visited) must
  stay 0 after warm restore + first report_checks
• Byte idempotence asserted on restore→write fixpoint (cold parallel
  search tag order is non-deterministic)

Explicit non-goals / gaps (v1)

• Multi-corner / multi-mode / POCV
• Parasitics (read_spef still required if you need them live)
• Liberty generated_clock definitions and network
  generatedClockPinsToCellMap_ (SDC create_generated_clock is fully
  supported; liberty-originated genclks that were already materialized into
  Sdc::clocks_ round-trip as normal generated clocks and report correctly,
  but cannot be re-spawned from liberty after restore)
• Linear / non-table delay models (rejected); CCS warned and dropped

Also in this PR

• Deletes .libdb (LibDb*, Tcl/SWIG entry points)
• Adds test/stadb and test/stadb_attrs regressions

[linear-code]

ENG-2416

[greptile-apps]

Greptile Summary

The PR replaces the Liberty-only .libdb cache with a .stadb session cache that restores Liberty, network, graph, constraints, and search state.

• Adds binary section codecs and readers/writers for linked and timed OpenSTA sessions.
• Adds Tcl/SWIG commands for reading and writing .stadb files.
• Adds restoration counters and regressions covering warm reports and post-restore edits.
• Removes the former .libdb implementation and command surface.

Confidence Score: 1/5

The PR is not safe to merge until malformed .stadb files can no longer trigger out-of-bounds reads or unbounded memory allocation.

The new file reader trusts arithmetic and allocation metadata from command-selected cache files, allowing crafted inputs to bypass section bounds or exhaust process memory before corruption handling can reject them.

Files Needing Attention: stadb/StaDbFile.cc, stadb/StaDbGraph.cc

Security Review

Two malformed-file paths require correction: overflowing section ranges can produce out-of-bounds reads, and unbounded decoded sizes/counts can exhaust process memory. How this was verified: The command-supplied file metadata was traced directly through the new range checks and allocation sites without intervening overflow-safe or payload-derived bounds.

Important Files Changed

Filename	Overview
stadb/StaDbFile.cc	Introduces the container format and section decoding, but its malformed-file validation permits an overflowing range and unbounded allocations.
stadb/StaDbReader.cc	Restores Liberty, network, graph, SDC, and search sections in the required dependency order.
stadb/StaDbWriter.cc	Serializes Liberty and network state and coordinates the remaining session sections.
stadb/StaDbGraph.cc	Rebuilds graph objects and timing data, including a collection count that should be bounded before allocation.
stadb/StaDbSdc.cc	Adds extensive tagged serialization and replay for constraint state.
stadb/StaDbSearch.cc	Restores search pools, paths, simulation state, and validity flags.
test/stadb.tcl	Exercises warm restoration, report equivalence, skip counters, editability, and byte stability.

Sequence Diagram

sequenceDiagram
  participant Tcl as read_sta_db
  participant File as DbFileReader
  participant Lib as Liberty reader
  participant Net as Network reader
  participant Graph as Graph reader
  participant Sdc as SDC reader
  participant Search as Search reader
  Tcl->>File: read(filename)
  File->>File: validate header and decode sections
  File-->>Lib: liberty section
  Lib-->>Net: restored libraries
  File-->>Net: network section
  File-->>Graph: graph section
  File-->>Sdc: constraints section
  File-->>Search: search section
  Search-->>Tcl: linked, constrained, timed session

Loading

_{Reviews (1): Last reviewed commit: "attribute tests" | Re-trigger Greptile}

[greptile-apps]

Overflowing section bounds check

When a .stadb section's 64-bit offset and stored size overflow when added, this check accepts an out-of-buffer range, causing the subsequent checksum, copy, or decompression operation to read out-of-bounds memory and potentially crash OpenSTA. Use subtraction-based bounds validation before constructing the pointer. How this was verified: Both range operands are decoded from the file as uint64_t values and their unchecked sum is validated immediately before the resulting pointer is read.

Suggested change

	if (offset + stored_size > file.size())
	throw DbCorrupt("stadb section extends past end of file");
	const uint8_t *stored = file.data() + offset;
	if (offset > file.size()
	|| stored_size > file.size() - offset)
	throw DbCorrupt("stadb section extends past end of file");
	const uint8_t *stored = file.data() + offset;

[greptile-apps]

Unbounded cache metadata allocations

When a small crafted .stadb declares an enormous decompressed size, string count, or graph-object count, the reader passes that metadata to resize or reserve before proving it is consistent with the bounded section payload, causing OpenSTA to terminate through allocation failure or operating-system OOM handling instead of rejecting the cache. Bound every allocation-driving value by format limits and available section bytes before allocating. How this was verified: File-controlled values flow directly into resize and reserve before any section-derived or explicit resource limit is enforced.

[stanminlee]

@gigeresk will take over