dbSta: POCV / LVF parametric statistical-OCV timing (draft)

[saurav-fermions]

Summary

Adds the dbSta POCV/LVF family — flag-gated, default-OFF parametric statistical-OCV commands. Statistical OCV models each stage delay as a distribution and combines independent per-stage variations in quadrature (sigma_path = k*sqrt(sum d_i^2)), which grows as sqrt(N) instead of the linear N of a flat derate. Every path is additive; default/flag-off is byte-identical to baseline.

1. POCV report slice (report-only) — set_pocv_sigma [-sigma k] [-n_sigma N] [-reset], report_checks_pocv; recomputes a quadrature (RSS) setup slack on already-found critical paths (flat-OCV vs POCV vs recovered pessimism). Does not modify the forward search.
2. Propagation-time derate — set_pocv_sigma -propagate injects per-stage variance (k*d_i)^2 into combinational data-path arcs during the forward search; native statistical delay-ops accumulate in quadrature (arrival +/- n_sigma*sqrt(var)).
3. Library-driven POCV — set_pocv_sigma -from_liberty sources per-stage sigma from real Liberty LVF ocv_sigma_* tables (per cell/arc); mutually exclusive with -sigma.
4. Table-indexed LVF test — proves the library path reads sigma as a 2-D table lookup over the same slew x load axes as the nominal delay table.

⚠️ Dependencies (please read)

• OpenSTA repair_tie_fanout multi-output tie cells #385 — the propagation/variance/from-liberty commands consume OpenSTA-fork statistical-engine hooks (Search::PocvSigma, variance injection in deratedDelayData, PocvSigma::from_liberty). CI here fails until repair_tie_fanout multi-output tie cells #385 is merged and this repo's src/sta is bumped. This PR carries no src/sta gitlink change. (repair_tie_fanout multi-output tie cells #385 in turn stacks on search/parasitics: AOCV depth-based derate hook + SI-window coupling-cap setter OpenSTA#383.)
• Test fixtures — the POCV/LVF regressions reuse the aocv_derate.def / aocv_derate.sdc fixtures introduced by the dbSta timing-accuracy PR dbSta: timing-accuracy report commands (AOCV/SI/PBA/CPPR/MCMM/crosstalk/noise/incremental-STA) #10846. Until that lands, those two fixture files must be present for the tests to run.

Testing

Built openroad against src/sta carrying the #385 hooks, with the AOCV fixtures present: all 6 POCV/LVF regressions pass and the full dbSta suite is green (76/76), including the flag-off byte-identical baseline checks.

Notes

• Marked draft pending the src/sta hooks (repair_tie_fanout multi-output tie cells #385) and the shared AOCV fixtures (dbSta: timing-accuracy report commands (AOCV/SI/PBA/CPPR/MCMM/crosstalk/noise/incremental-STA) #10846).
• All commands additive / flag-gated / report-only; no default behavior change.

[gemini-code-assist]

Code Review

This pull request introduces parametric statistical on-chip-variation (POCV / LVF) derating to dbSta, adding C++ implementations for statistical slack adjustment, SWIG bindings for configuration and propagation, Tcl commands, and comprehensive integration tests. The review feedback focuses on improving robustness by adding null pointer checks across several SWIG/C++ functions in dbSta.i to prevent potential crashes, as well as checking for empty lists in the Tcl reporting loop to avoid runtime errors.

[gemini-code-assist]

Add a null check for sta and sta->search() before calling setPocvSigma to prevent a potential crash if STA is not fully initialized.

static void
pocvSyncState()
{
  ord::OpenRoad *openroad = ord::getOpenRoad();
  sta::dbSta *sta = openroad->getSta();
  if (sta != nullptr && sta->search() != nullptr) {
    sta->search()->setPocvSigma(pocvSigmaState());
  }
}

[gemini-code-assist]

Add a null check for sta before calling setPocvQuantile and setPocvMode to prevent a potential crash.

void
pocv_sigma_set_propagate(float per_stage,
                         float n_sigma)
{
  Search::PocvSigma &s = pocvSigmaState();
  s.enabled = true;
  s.per_stage = per_stage;
  s.n_sigma = n_sigma;
  s.propagate = true;
  pocvSyncState();

  ord::OpenRoad *openroad = ord::getOpenRoad();
  sta::dbSta *sta = openroad->getSta();
  if (sta != nullptr) {
    // n_sigma is the sign-off quantile used by DelayOpsNormal::asFloat.
    sta->setPocvQuantile(n_sigma);
    // Statistical readout of the accumulated variance.
    sta->setPocvMode(sta::PocvMode::normal);
  }
}

[gemini-code-assist]

Add comprehensive null checks for sta, sta->network(), lib_iter, lib, cell, arc_set, and arc to prevent potential null pointer dereferences and crashes when iterating over loaded libraries.

static bool
anyLibraryHasLvf()
{
  ord::OpenRoad *openroad = ord::getOpenRoad();
  sta::dbSta *sta = openroad->getSta();
  if (sta == nullptr || sta->network() == nullptr) {
    return false;
  }
  LibertyLibraryIterator *lib_iter = sta->network()->libertyLibraryIterator();
  if (lib_iter == nullptr) {
    return false;
  }
  bool found = false;
  while (lib_iter->hasNext() && !found) {
    LibertyLibrary *lib = lib_iter->next();
    if (lib == nullptr) {
      continue;
    }
    LibertyCellIterator cell_iter(lib);
    while (cell_iter.hasNext() && !found) {
      LibertyCell *cell = cell_iter.next();
      if (cell == nullptr) {
        continue;
      }
      for (TimingArcSet *arc_set : cell->timingArcSets()) {
        if (arc_set == nullptr) {
          continue;
        }
        if (arc_set->role() != TimingRole::combinational())
          continue;
        for (TimingArc *arc : arc_set->arcs()) {
          if (arc == nullptr) {
            continue;
          }
          const TimingModel *model = arc->model();
          const GateTableModel *gate
              = dynamic_cast<const GateTableModel *>(model);
          if (gate && gate->delayModels()) {
            const TableModels *dm = gate->delayModels();
            if (dm && (dm->sigma(MinMax::max()) || dm->sigma(MinMax::min())
                || dm->stdDev())) {
              found = true;
              break;
            }
          }
        }
        if (found)
          break;
      }
    }
  }
  delete lib_iter;
  return found;
}

[gemini-code-assist]

Add a null check for sta before calling setPocvQuantile and setPocvMode to prevent a potential crash.

void
pocv_sigma_set_from_liberty(float n_sigma)
{
  Search::PocvSigma &s = pocvSigmaState();
  s.enabled = true;
  s.per_stage = 0.0f;     // unused in library mode (sigma is per-cell from LVF)
  s.n_sigma = n_sigma;
  s.propagate = true;     // library variance still flows through propagation
  s.from_liberty = true;  // ... but via native LVF, not synthetic injection
  pocvSyncState();

  ord::OpenRoad *openroad = ord::getOpenRoad();
  sta::dbSta *sta = openroad->getSta();
  if (sta != nullptr) {
    sta->setPocvQuantile(n_sigma);
    sta->setPocvMode(sta::PocvMode::normal);
  }
}

[gemini-code-assist]

Add a null check for sta before calling setPocvMode to prevent a potential crash.

void
pocv_sigma_clear()
{
  const bool was_propagate = pocvSigmaState().propagate;
  pocvSigmaState() = Search::PocvSigma();  // back to inactive default
  pocvSyncState();
  // OpenROAD-fork: LVF -- if propagation mode had been enabled, return the
  // timer to scalar delay-ops so timing is byte-identical to baseline again.
  if (was_propagate) {
    ord::OpenRoad *openroad = ord::getOpenRoad();
    sta::dbSta *sta = openroad->getSta();
    if (sta != nullptr) {
      sta->setPocvMode(sta::PocvMode::scalar);
    }
  }
}

[gemini-code-assist]

Add null checks for sta, path_end, and time_unit to prevent potential null pointer dereferences and crashes.

StringSeq
pocv_adjust_path_end(PathEnd *path_end)
{
  ord::OpenRoad *openroad = ord::getOpenRoad();
  sta::dbSta *sta = openroad->getSta();
  if (sta == nullptr || path_end == nullptr) {
    return StringSeq();
  }
  PocvPathResult r = pocvAdjustPathEnd(sta, path_end, pocvSigmaState());
  sta::Unit *time_unit = sta->units()->timeUnit();
  if (time_unit == nullptr) {
    return StringSeq();
  }
  auto fmt = [](double v) {
    std::ostringstream ss;
    ss.setf(std::ios::fixed);
    ss << std::setprecision(9) << v;
    return ss.str();
  };
  StringSeq out;
  out.push_back(r.endpoint);
  out.push_back(std::to_string(r.logic_depth));
  out.push_back(fmt(time_unit->staToUser(r.flat_slack)));
  out.push_back(fmt(time_unit->staToUser(r.pocv_slack)));
  out.push_back(fmt(time_unit->staToUser(r.flat_sigma)));
  out.push_back(fmt(time_unit->staToUser(r.rss_sigma)));
  out.push_back(fmt(r.n_sigma));
  return out;
}

[gemini-code-assist]

Add null checks for sta, path_end, and time_unit to prevent potential null pointer dereferences and crashes.

StringSeq
pocv_path_end_stat_slack(PathEnd *path_end)
{
  ord::OpenRoad *openroad = ord::getOpenRoad();
  sta::dbSta *sta = openroad->getSta();
  if (sta == nullptr || path_end == nullptr) {
    return StringSeq();
  }
  const sta::Slack slack = path_end->slack(sta);
  const float mean = slack.mean();
  const float std_dev = slack.stdDev();
  const float n_sigma = pocvSigmaState().n_sigma;
  // Worst-case statistical slack: pull the slack down by n_sigma sigmas.
  const float stat = mean - n_sigma * std_dev;
  sta::Unit *time_unit = sta->units()->timeUnit();
  if (time_unit == nullptr) {
    return StringSeq();
  }
  auto fmt = [](double v) {
    std::ostringstream ss;
    ss.setf(std::ios::fixed);
    ss << std::setprecision(9) << v;
    return ss.str();
  };
  StringSeq out;
  out.push_back(fmt(time_unit->staToUser(mean)));
  out.push_back(fmt(time_unit->staToUser(std_dev)));
  out.push_back(fmt(time_unit->staToUser(stat)));
  out.push_back(fmt(n_sigma));
  return out;
}

[gemini-code-assist]

Check if row is empty before assigning variables and calculating recovered to prevent a potential Tcl runtime error if pocv_adjust_path_end returns an empty list.

  foreach path_end $path_ends {
    set row [sta::pocv_adjust_path_end $path_end]
    if { $row == {} } {
      continue
    }
    lassign $row endpoint depth flat pocv lin_sigma rss_sigma n_sigma

[saurav-fermions]

Thanks for the review. Note this PR is a draft — it depends on the OpenSTA POCV/LVF hooks in The-OpenROAD-Project/OpenSTA#385 (and reuses the AOCV test fixtures from #10846), so CI can't go green until those land.

• Empty path-end guard (report_checks_pocv): added — pocv_adjust_path_end returning an empty list is now skipped instead of hitting a lassign/expr error.

• The sta/network/iterator null-checks flagged on the SWIG entry points: these commands follow the existing dbSta command pattern — ord::getOpenRoad()->getSta() is always valid once the app is initialized, and ensureLinked()/ensureGraph() guard the timing state before use, exactly like the sibling report_checks_* commands. Adding per-call null-checks there would be dead code inconsistent with the rest of dbSta.i, so I've left those as-is; happy to reconsider if the team wants defensive guards added uniformly.

• Also removed an accidental src/sta submodule bump.