feat: sdc collections

.github/workflows/tests.yaml

@@ -17,7 +17,7 @@ jobs:
           cp Dockerfile.${{ matrix.os }} Dockerfile
           docker build --tag sta-${{ matrix.os }} .
       - run: |
-          docker run --entrypoint /bin/bash --tty --rm sta-${{ matrix.os }} -c "cd /OpenSTA/test && ./regression || (cat results/diffs && exit 1)"
+          docker run --entrypoint /bin/bash --tty --rm sta-${{ matrix.os }} -c "cd /OpenSTA/test && (./regression || (cat results/diffs && exit 1)) || (./regression -collections || (cat results/diffs && exit 1))"
 
   macos:
     runs-on: [macos-14]
@@ -42,3 +42,4 @@ jobs:
       - run: |
           cd test
           ./regression || (cat results/diffs && exit 1)
+          ./regression -collections || (cat results/diffs && exit 1)

.github/workflows/valgrind.ubuntu22.04.Dockerfile

@@ -0,0 +1,15 @@
+# further run memory leak checks with valgrind
+FROM sta-ubuntu-22.04
+
+RUN apt-get install -y valgrind
+
+RUN cd /OpenSTA &&\
+    rm -rf build &&\
+    mkdir build &&\
+    cd build &&\
+    cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS='-O0' -DCUDD_DIR=../cudd-3.0.0 .. && \
+    make -j`nproc` VERBOSE=1
+
+RUN cd /OpenSTA/test &&\
+    ./regression -valgrind -j`nproc`&&\
+    ./regression -valgrind -collections -j`nproc`

CMakeLists.txt

@@ -432,6 +432,7 @@ set(SWIG_FILES
   ${STA_HOME}/search/Search.i
   ${STA_HOME}/spice/WriteSpice.i
   ${STA_HOME}/tcl/Exception.i
+  ${STA_HOME}/tcl/Collections.i
   ${STA_HOME}/tcl/StaTclTypes.i
   ${STA_HOME}/util/Util.i
   ${STA_HOME}/verilog/Verilog.i

include/sta/FilterExpr.hh

@@ -26,8 +26,13 @@
 
 #include <string>
 #include <memory>
+#include <stack>
+#include <set>
 #include "StringSeq.hh"
 #include "Error.hh"
+#include "Sta.hh"
+#include "Property.hh"
+#include "PatternMatch.hh"
 
 namespace sta {
 
@@ -83,4 +88,165 @@ private:
     std::string raw_;
 };
 
+template <typename T> std::set<T*>
+process_predicate(const char *property,
+	       const char *op,
+	       const char *pattern,
+	       std::set<T*> &all)
+{
+  auto filtered_objects = std::set<T*>();
+  bool exact_match = stringEq(op, "==");
+  bool pattern_match = stringEq(op, "=~");
+  bool not_match = stringEq(op, "!=");
+  bool not_pattern_match = stringEq(op, "!~");
+  for (T *object : all) {
+    PropertyValue value = Sta::sta()->properties().getProperty(object, property);
+    std::string prop_str = value.to_string(Sta::sta()->network());
+    const char *prop = prop_str.c_str();
+    if (prop &&
+        ((exact_match && stringEq(prop, pattern))
+          || (not_match && !stringEq(prop, pattern))
+          || (pattern_match && patternMatch(pattern, prop))
+          || (not_pattern_match && !patternMatch(pattern, prop))))
+      filtered_objects.insert(object);
+  }
+  return filtered_objects;
+}
+
+template <typename T> Vector<T*>
+filter_objects(const char *filter_expression,
+	       Vector<T*> *objects,
+         bool sta_boolean_props_as_int
+        ) {
+  Vector<T*> result;
+  if (objects) {
+    auto all = std::set<T*>();
+    for (auto object: *objects) {
+      all.insert(object);
+    }
+    auto postfix = sta::FilterExpr(filter_expression).postfix(sta_boolean_props_as_int);
+    std::stack<std::set<T*>> eval_stack;
+    for (auto &pToken: postfix) {
+      if (pToken->kind == sta::FilterExpr::Token::Kind::op_or) {
+        if (eval_stack.size() < 2) {
+          throw sta::FilterError("attempted to run a logical or on less than two predicates");
+        }
+        auto arg0 = eval_stack.top();
+        eval_stack.pop();
+        auto arg1 = eval_stack.top();
+        eval_stack.pop();
+        auto union_result = std::set<T*>();
+        std::set_union(
+          arg0.cbegin(), arg0.cend(),
+          arg1.cbegin(), arg1.cend(),
+          std::inserter(union_result, union_result.begin())
+        );
+        eval_stack.push(union_result);
+      } else if (pToken->kind == sta::FilterExpr::Token::Kind::op_and) {
+        if (eval_stack.size() < 2) {
+          throw sta::FilterError("attempted to run a logical and on less than two predicates");
+        }
+        auto arg0 = eval_stack.top();
+        eval_stack.pop();
+        auto arg1 = eval_stack.top();
+        eval_stack.pop();
+        auto intersection_result = std::set<T*>();
+        std::set_intersection(
+          arg0.cbegin(), arg0.cend(),
+          arg1.cbegin(), arg1.cend(),
+          std::inserter(intersection_result, intersection_result.begin())
+        );
+        eval_stack.push(intersection_result);
+      } else if (pToken->kind == sta::FilterExpr::Token::Kind::op_inv) {
+        if (eval_stack.size() < 1) {
+          throw sta::FilterError("attempted to run an inversion on no predicates");
+        }
+        auto arg0 = eval_stack.top();
+        eval_stack.pop();
+
+        auto difference_result = std::set<T*>();
+        std::set_difference(
+          all.cbegin(), all.cend(),
+          arg0.cbegin(), arg0.cend(),
+          std::inserter(difference_result, difference_result.begin())
+        );
+        eval_stack.push(difference_result);
+      } else if (pToken->kind == sta::FilterExpr::Token::Kind::defined ||
+                 pToken->kind == sta::FilterExpr::Token::Kind::undefined) {
+        bool should_be_defined = (pToken->kind == sta::FilterExpr::Token::Kind::defined);
+        auto result = std::set<T*>();
+        for (auto object : all) {
+          PropertyValue value = Sta::sta()->properties().getProperty(object, pToken->text);
+          bool is_defined = false;
+          switch (value.type()) {
+            case PropertyValue::Type::type_float:
+              is_defined = value.floatValue() != 0;
+              break;
+            case PropertyValue::Type::type_bool:
+              is_defined = value.boolValue();
+              break;
+            case PropertyValue::Type::type_string:
+            case PropertyValue::Type::type_liberty_library:
+            case PropertyValue::Type::type_liberty_cell:
+            case PropertyValue::Type::type_liberty_port:
+            case PropertyValue::Type::type_library:
+            case PropertyValue::Type::type_cell:
+            case PropertyValue::Type::type_port:
+            case PropertyValue::Type::type_instance:
+            case PropertyValue::Type::type_pin:
+            case PropertyValue::Type::type_net:
+            case PropertyValue::Type::type_clk:
+              is_defined = value.to_string(Sta::sta()->network()) != "";
+              break;
+            case PropertyValue::Type::type_none:
+              is_defined = false;
+              break;
+            case PropertyValue::Type::type_pins:
+              is_defined = value.pins()->size() > 0;
+              break;
+            case PropertyValue::Type::type_clks:
+              is_defined = value.clocks()->size() > 0;
+              break;
+            case PropertyValue::Type::type_paths:
+              is_defined = value.paths()->size() > 0;
+              break;
+            case PropertyValue::Type::type_pwr_activity:
+              is_defined = value.pwrActivity().isSet();
+              break;
+          }
+          if (is_defined == should_be_defined) {
+            result.insert(object);
+          }
+        }
+        eval_stack.push(result);
+      } else if (pToken->kind == sta::FilterExpr::Token::Kind::predicate) {
+        auto predicate_token = std::static_pointer_cast<sta::FilterExpr::PredicateToken>(pToken);
+        auto predicate_result = process_predicate<T>(predicate_token->property.c_str(), predicate_token->op.c_str(), predicate_token->arg.c_str(), all);
+        eval_stack.push(predicate_result);
+      }
+    }
+    if (eval_stack.size() == 0) {
+      throw sta::FilterError("filter expression is empty");
+    }
+    if (eval_stack.size() > 1) {
+      throw sta::FilterError("filter expression evaluated to multiple sets");
+    }
+    auto result_set = eval_stack.top();
+    result.resize(result_set.size());
+    std::copy(result_set.begin(), result_set.end(), result.begin());
+
+    // Maintain pre-filter ordering
+    std::map<T*, int> objects_i;
+    for (int i = 0; i < objects->size(); ++i)
+      objects_i[objects->at(i)] = i;
+
+    std::sort(result.begin(), result.end(),
+      [&](T* a, T* b) {
+          return objects_i[a] < objects_i[b];
+    });
+  }
+  return result;
+}
+
+
 } // namespace

include/sta/FindObjects.hh

@@ -0,0 +1,66 @@
+// OpenSTA, Static Timing Analyzer
+// Copyright (c) 2025, Parallax Software, Inc.
+// 
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+// 
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+// 
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+// 
+// The origin of this software must not be misrepresented; you must not
+// claim that you wrote the original software.
+// 
+// Altered source versions must be plainly marked as such, and must not be
+// misrepresented as being the original software.
+// 
+// This notice may not be removed or altered from any source distribution.
+
+#pragma once
+
+#include "PatternMatch.hh"
+#include "FilterExpr.hh"
+#include <functional>
+
+
+template <class SEQ_TYPE, class OBJECT_TYPE, int ERROR_CODE, const char * OBJECT_TYPE_NAME>
+SEQ_TYPE *
+find_objects_complete(SEQ_TYPE *collection,
+                      StringSeq *patterns,
+                      bool regexp,
+                      bool nocase,
+                      bool quiet,
+                      const char *filter_expression,
+                      std::function<SEQ_TYPE(PatternMatch *)> get_pattern)
+{
+  collection = collection ? new SEQ_TYPE(*collection) : new SEQ_TYPE();
+  auto sta = Sta::sta();
+  for (const char *pattern: *patterns) {
+    PatternMatch matcher(pattern, regexp, nocase, sta->tclInterp());
+    auto result = get_pattern(&matcher);
+    if (result.size() == 0) {
+        if (!quiet)
+          sta->report()->warn(ERROR_CODE, "%s '%s' not found.", OBJECT_TYPE_NAME, pattern);
+    } else {
+      auto entries = collection->size();
+      collection->resize(entries + result.size());
+      std::move(
+        result.begin(),
+        result.end(),
+        collection->begin() + entries
+      );
+    }
+  }
+  if (filter_expression != nullptr) {
+    auto filtered = filter_objects<OBJECT_TYPE>(filter_expression, collection, sta->booleanPropsAsInt());
+    delete collection;
+    collection = new SEQ_TYPE(filtered);
+  }
+  return collection;
+}

include/sta/LibertyClass.hh

@@ -69,11 +69,14 @@ class Statetable;
 class StatetableRow;
 
 typedef Vector<LibertyLibrary*> LibertyLibrarySeq;
+typedef LibertyLibrarySeq::ConstIterator LibertyLibrarySeqIterator;
 typedef Vector<LibertyCell*> LibertyCellSeq;
+typedef LibertyCellSeq::ConstIterator LibertyCellSeqIterator;
 typedef Vector<Sequential*> SequentialSeq;
 typedef Vector<GeneratedClock*> GeneratedClockSeq;
 typedef Map<LibertyCell*, LibertyCellSeq*> LibertyCellEquivMap;
 typedef Vector<LibertyPort*> LibertyPortSeq;
+typedef LibertyPortSeq::ConstIterator LibertyPortSeqIterator;
 typedef Set<LibertyPort*> LibertyPortSet;
 typedef std::pair<const LibertyPort*,const LibertyPort*> LibertyPortPair;
 typedef Set<LibertyCell*> LibertyCellSet;

include/sta/NetworkClass.hh

@@ -52,14 +52,19 @@ class LibertyLibrary;
 typedef Iterator<Library*> LibraryIterator;
 typedef Iterator<LibertyLibrary*> LibertyLibraryIterator;
 typedef Vector<Cell*> CellSeq;
+typedef CellSeq::ConstIterator CellSeqIterator;
 typedef Vector<const Port*> PortSeq;
+typedef PortSeq::ConstIterator PortSeqIterator;
 typedef Iterator<Port*> CellPortIterator;
 typedef Iterator<Port*> CellPortBitIterator;
 typedef Iterator<Port*> PortMemberIterator;
 
 typedef Vector<const Pin*> PinSeq;
+typedef PinSeq::ConstIterator PinSeqIterator;
 typedef Vector<const Instance*> InstanceSeq;
+typedef InstanceSeq::ConstIterator InstanceSeqIterator;
 typedef Vector<const Net*> NetSeq;
+typedef NetSeq::ConstIterator NetSeqIterator;
 typedef std::vector<const Net*> ConstNetSeq;
 typedef Iterator<Instance*> InstanceChildIterator;
 typedef Iterator<Pin*> InstancePinIterator;

include/sta/Property.hh

@@ -171,6 +171,8 @@ protected:
 //  constructor
 //  copy constructor switch clause
 //  move constructor switch clause
+//  type_name switch clause
+//  compare switch clause
 //  operator= &  switch clause
 //  operator= && switch clause
 //  StaTcl.i swig %typemap(out) PropertyValue switch clause
@@ -183,6 +185,7 @@ public:
 	      type_liberty_library, type_liberty_cell, type_liberty_port,
 	      type_instance, type_pin, type_pins, type_net,
 	      type_clk, type_clks, type_paths, type_pwr_activity };
+  static const char *type_name(Type type);
   PropertyValue();
   PropertyValue(const char *value);
   PropertyValue(std::string &value);
@@ -238,6 +241,9 @@ public:
   // Move assignment.
   PropertyValue &operator=(PropertyValue &&);
 
+  // Comparison
+  int compare(const PropertyValue &rhs, const Network *network, bool natural = false) const;
+
 private:
   Type type_;
   union {

include/sta/SdcClass.hh

@@ -83,6 +83,7 @@ public:
 typedef Vector<float> FloatSeq;
 typedef Vector<int> IntSeq;
 typedef Vector<Clock*> ClockSeq;
+typedef ClockSeq::ConstIterator ClockSeqIterator;
 typedef std::vector<const Clock*> ConstClockSeq;
 typedef Set<Clock*, ClockIndexLess> ClockSet;
 typedef std::set<const Clock*, ClockIndexLess> ConstClockSet;

include/sta/Sta.hh

@@ -1360,6 +1360,9 @@ public:
   // TCL variable sta_strip_escaped_bus.
   bool stripEscapedBus() const;
   void setStripEscapedBus(bool enable);
+  // TCL variable sta_enable_collections
+  bool enableCollections() const;
+  void setEnableCollections(bool enable);
   ////////////////////////////////////////////////////////////////
 
   Properties &properties() { return properties_; }

include/sta/TclTypeHelpers.hh

@@ -38,6 +38,10 @@ StringSet *
 tclListSetConstChar(Tcl_Obj *const source,
 		    Tcl_Interp *interp);
 
+int
+tclListSeqConstCharCheck(Tcl_Obj *const source,
+		 	 Tcl_Interp *interp);
+
 StringSeq *
 tclListSeqConstChar(Tcl_Obj *const source,
 		    Tcl_Interp *interp);

include/sta/Variables.hh

@@ -98,6 +98,10 @@ public:
   // TCL variable sta_strip_escaped_bus.
   bool stripEscapedBus() const { return strip_escaped_bus_; }
   void setStripEscapedBus(bool enable) { strip_escaped_bus_ = enable; }
+  // TCL variable sta_enable_collections
+  bool enableCollections() const { return enable_collections_; }
+  void setEnableCollections(bool enable) { enable_collections_ = enable; }
+
 
 private:
   bool crpr_enabled_;
@@ -122,6 +126,7 @@ private:
   bool no_inv_delay_calc_;
   bool no_inv_power_calc_;
   bool strip_escaped_bus_;
+  bool enable_collections_;
 };
 
 } // namespace