odb: adding comments to the scan structs

Signed-off-by: Felipe Garay <fgaray@google.com>

src/odb/include/odb/db.h

@@ -7091,6 +7091,7 @@ class dbAccessPoint : public dbObject
   // User Code End dbAccessPoint
 };
 
+// Top level DFT (Design for Testing) class
 class dbDft : public dbObject
 {
  public:
@@ -7757,13 +7758,16 @@ class dbPowerSwitch : public dbObject
   // User Code End dbPowerSwitch
 };
 
+// A scan chain is a collection of dbScanLists that contains dbScanInsts.  Here,
+// scan_in, scan_out and scan_enable are the top level ports/pins to where this
+// scan chain is connected.  Each scan chain is also associated with a
+// particular test mode and test mode pin that puts the Circuit Under Test (CUT)
+// in test. The Scan Enable port/pin puts the scan chain into shifting mode.
 class dbScanChain : public dbObject
 {
  public:
   dbSet<dbScanPartition> getScanPartitions() const;
 
-  dbSet<dbScanList> getScanLists() const;
-
   // User Code Begin dbScanChain
   const std::string& getName() const;
 
@@ -7792,6 +7796,14 @@ class dbScanChain : public dbObject
   // User Code End dbScanChain
 };
 
+// A scan inst is a cell with a scan in, scan out and an optional scan enable.
+// If no scan enable is provided, then this is an stateless component (because
+// we don't need to enable scan for it) and the number of bits is set to 0.  It
+// may be possible that two or more dbScanInst contains the same dbInst if the
+// dbInst has more than one scan_in/scan_out pair. Examples of those cases are
+// multibit cells with external scan or black boxes.  In this case, the scan_in,
+// scan_out and scan enables are pins in the dbInst. The scan clock is the pin
+// that we use to shift patterns in and out of the scan chain.
 class dbScanInst : public dbObject
 {
  public:
@@ -7831,41 +7843,46 @@ class dbScanInst : public dbObject
   // User Code End dbScanInst
 };
 
+// A scan list is a collection of dbScanInsts in a particular order that must be
+// respected when performing scan reordering and repartitioning. For ScanList
+// with two or more elements we say that they are ORDERED. If the ScanList
+// contains only one element then they are FLOATING elements that don't have any
+// restriccion when optimizing the scan chain.
 class dbScanList : public dbObject
 {
  public:
   dbSet<dbScanInst> getScanInsts() const;
 
   // User Code Begin dbScanList
   dbScanInst* add(dbInst* inst);
-  static dbScanList* create(dbScanChain* scan_chain);
+  static dbScanList* create(dbScanPartition* scan_partition);
   // User Code End dbScanList
 };
 
+// A scan partition is way to split the scan chains into sub chains with
+// compatible scan flops (same clock, edge and voltage). The biggest partition
+// possible is the whole chain if all the scan flops inside it are compatible
+// between them for reordering and repartitioning. The name of this partition is
+// not unique, as multiple partitions may have the same same and therefore
+// contain the same type of flops.
 class dbScanPartition : public dbObject
 {
  public:
-  // User Code Begin dbScanPartition
-  void setStart(dbBTerm* bterm);
-
-  void setStart(dbITerm* iterm);
-
-  void setStop(dbBTerm* bterm);
-
-  void setStop(dbITerm* iterm);
-
-  std::variant<dbBTerm*, dbITerm*> getStart() const;
-
-  std::variant<dbBTerm*, dbITerm*> getStop() const;
+  dbSet<dbScanList> getScanLists() const;
 
+  // User Code Begin dbScanPartition
   const std::string& getName() const;
-
-  void setName(std::string_view name);
+  void setName(const std::string& name);
 
   static dbScanPartition* create(dbScanChain* chain);
   // User Code End dbScanPartition
 };
 
+// This is a helper class to contain dbBTerms and dbITerms in the same field. We
+// need this difference because some pins may need to be conected to top level
+// ports or cell's pins.  For example: a scan chain may be connected to a top
+// level design port (dbBTerm) or to an output/input pin of a cell that is part
+// of a decompressor/compressor
 class dbScanPin : public dbObject
 {
  public:

src/odb/src/codeGenerator/schema.json

@@ -253,7 +253,8 @@
       "type":"1_n",
       "tbl_name":"two_wires_forbidden_spc_rules_tbl_",
       "schema":"db_schema_lef58_two_wires_forbidden_spacing"
-    }
+    },
+    {
       "first": "dbDft",
       "second": "dbScanPin",
       "type": "1_n",
@@ -267,7 +268,7 @@
       "tbl_name": "scan_partitions_"
     },
     {
-      "first": "dbScanChain",
+      "first": "dbScanPartition",
       "second": "dbScanList",
       "type": "1_n",
       "tbl_name": "scan_lists_"

src/odb/src/codeGenerator/schema/scan/dbDft.json

@@ -1,6 +1,7 @@
 {
   "name": "dbDft",
   "type": "dbObject",
+  "description": ["Top level DFT (Design for Testing) class"],
   "fields": [
     {
       "name": "scan_inserted_",

src/odb/src/codeGenerator/schema/scan/dbScanChain.json

@@ -1,6 +1,11 @@
 {
   "name": "dbScanChain",
   "type": "dbObject",
+  "description": ["A scan chain is a collection of dbScanLists that contains dbScanInsts.  Here,",
+    "scan_in, scan_out and scan_enable are the top level ports/pins to where this",
+    "scan chain is connected.  Each scan chain is also associated with a particular",
+    "test mode and test mode pin that puts the Circuit Under Test (CUT) in test. The",
+    "Scan Enable port/pin puts the scan chain into shifting mode."],
   "fields": [
     {
       "name": "name_",

src/odb/src/codeGenerator/schema/scan/dbScanInst.json

@@ -1,6 +1,15 @@
 {
   "name": "dbScanInst",
   "type": "dbObject",
+  "description":
+    ["A scan inst is a cell with a scan in, scan out and an optional scan enable. If",
+    "no scan enable is provided, then this is an stateless component (because we",
+    "don't need to enable scan for it) and the number of bits is set to 0.  It may",
+    "be possible that two or more dbScanInst contains the same dbInst if the dbInst",
+    "has more than one scan_in/scan_out pair. Examples of those cases are multibit",
+    "cells with external scan or black boxes.  In this case, the scan_in, scan_out",
+    "and scan enables are pins in the dbInst. The scan clock is the pin that we use",
+    "to shift patterns in and out of the scan chain."],
   "fields": [
     {
       "name": "bits_",
@@ -73,6 +82,7 @@
     "dbScanPin.h",
     "dbDft.h",
     "dbScanChain.h",
-    "dbScanList.h"
+    "dbScanList.h",
+    "dbScanPartition.h"
   ]
 }

src/odb/src/codeGenerator/schema/scan/dbScanList.json

@@ -1,7 +1,14 @@
 {
   "name": "dbScanList",
   "type": "dbObject",
+  "description": [
+    "A scan list is a collection of dbScanInsts in a particular order that must be",
+    "respected when performing scan reordering and repartitioning. For ScanList with",
+    "two or more elements we say that they are ORDERED. If the ScanList contains only",
+    "one element then they are FLOATING elements that don't have any restriccion when",
+    "optimizing the scan chain."],
   "cpp_includes": [
-    "dbScanChain.h"
+    "dbScanChain.h",
+    "dbScanPartition.h"
   ]
 }

src/odb/src/codeGenerator/schema/scan/dbScanPartition.json

@@ -1,17 +1,15 @@
 {
   "name": "dbScanPartition",
   "type": "dbObject",
+  "description": [
+    "A scan partition is way to split the scan chains into sub chains with compatible",
+    "scan flops (same clock, edge and voltage). The biggest partition possible is the",
+    "whole chain if all the scan flops inside it are compatible between them for",
+    "reordering and repartitioning. The name of this partition is not unique, as",
+    "multiple partitions may have the same same and therefore contain the same type",
+    "of flops."
+  ],
   "fields": [
-    {
-      "name": "start_",
-      "type": "dbId<dbScanPin>",
-      "flags": ["private"]
-    },
-    {
-      "name": "stop_",
-      "type": "dbId<dbScanPin>",
-      "flags": ["private"]
-    },
     {
       "name": "name_",
       "type": "std::string",

src/odb/src/codeGenerator/schema/scan/dbScanPin.json

@@ -1,6 +1,13 @@
 {
   "name": "dbScanPin",
   "type": "dbObject",
+  "description": [
+    "This is a helper class to contain dbBTerms and dbITerms in the same field. We",
+    "need this difference because some pins may need to be conected to top level",
+    "ports or cell's pins.  For example: a scan chain may be connected to a top level",
+    "design port (dbBTerm) or to an output/input pin of a cell that is part of a",
+    "decompressor/compressor"
+  ],
   "fields": [
     {
       "name": "pin_",

src/odb/src/codeGenerator/templates/db.h

@@ -6,6 +6,11 @@ class {{klass.name}};
 //Generator Code Begin ClassDefinition
 {% for klass in schema.classes|sort(attribute='name') %}
 
+{% if klass.description %}
+  {% for line in klass.description %}
+    // {{ line }}
+  {% endfor %}
+{% endif %}
 class {{klass.name}} : public dbObject
 {
  public:

src/odb/src/db/dbScanChain.cpp

@@ -39,7 +39,6 @@
 #include "dbDft.h"
 #include "dbDiff.hpp"
 #include "dbScanInst.h"
-#include "dbScanList.h"
 #include "dbScanPartition.h"
 #include "dbScanPin.h"
 #include "dbSet.h"
@@ -71,9 +70,6 @@ bool _dbScanChain::operator==(const _dbScanChain& rhs) const
   if (*scan_partitions_ != *rhs.scan_partitions_) {
     return false;
   }
-  if (*scan_lists_ != *rhs.scan_lists_) {
-    return false;
-  }
 
   return true;
 }
@@ -95,7 +91,6 @@ void _dbScanChain::differences(dbDiff& diff,
   DIFF_FIELD(test_mode_);
   DIFF_FIELD(test_mode_name_);
   DIFF_TABLE(scan_partitions_);
-  DIFF_TABLE(scan_lists_);
   DIFF_END
 }
 
@@ -109,7 +104,6 @@ void _dbScanChain::out(dbDiff& diff, char side, const char* field) const
   DIFF_OUT_FIELD(test_mode_);
   DIFF_OUT_FIELD(test_mode_name_);
   DIFF_OUT_TABLE(scan_partitions_);
-  DIFF_OUT_TABLE(scan_lists_);
 
   DIFF_END
 }
@@ -121,8 +115,6 @@ _dbScanChain::_dbScanChain(_dbDatabase* db)
       this,
       (GetObjTbl_t) &_dbScanChain::getObjectTable,
       dbScanPartitionObj);
-  scan_lists_ = new dbTable<_dbScanList>(
-      db, this, (GetObjTbl_t) &_dbScanChain::getObjectTable, dbScanListObj);
 }
 
 _dbScanChain::_dbScanChain(_dbDatabase* db, const _dbScanChain& r)
@@ -135,7 +127,6 @@ _dbScanChain::_dbScanChain(_dbDatabase* db, const _dbScanChain& r)
   test_mode_name_ = r.test_mode_name_;
   scan_partitions_
       = new dbTable<_dbScanPartition>(db, this, *r.scan_partitions_);
-  scan_lists_ = new dbTable<_dbScanList>(db, this, *r.scan_lists_);
 }
 
 dbIStream& operator>>(dbIStream& stream, _dbScanChain& obj)
@@ -147,7 +138,6 @@ dbIStream& operator>>(dbIStream& stream, _dbScanChain& obj)
   stream >> obj.test_mode_;
   stream >> obj.test_mode_name_;
   stream >> *obj.scan_partitions_;
-  stream >> *obj.scan_lists_;
   return stream;
 }
 
@@ -160,7 +150,6 @@ dbOStream& operator<<(dbOStream& stream, const _dbScanChain& obj)
   stream << obj.test_mode_;
   stream << obj.test_mode_name_;
   stream << *obj.scan_partitions_;
-  stream << *obj.scan_lists_;
   return stream;
 }
 
@@ -169,8 +158,6 @@ dbObjectTable* _dbScanChain::getObjectTable(dbObjectType type)
   switch (type) {
     case dbScanPartitionObj:
       return scan_partitions_;
-    case dbScanListObj:
-      return scan_lists_;
     default:
       break;
   }
@@ -180,7 +167,6 @@ dbObjectTable* _dbScanChain::getObjectTable(dbObjectType type)
 _dbScanChain::~_dbScanChain()
 {
   delete scan_partitions_;
-  delete scan_lists_;
 }
 
 ////////////////////////////////////////////////////////////////////
@@ -195,12 +181,6 @@ dbSet<dbScanPartition> dbScanChain::getScanPartitions() const
   return dbSet<dbScanPartition>(obj, obj->scan_partitions_);
 }
 
-dbSet<dbScanList> dbScanChain::getScanLists() const
-{
-  _dbScanChain* obj = (_dbScanChain*) this;
-  return dbSet<dbScanList>(obj, obj->scan_lists_);
-}
-
 // User Code Begin dbScanChainPublicMethods
 
 const std::string& dbScanChain::getName() const

src/odb/src/db/dbScanChain.h

@@ -47,7 +47,6 @@ class dbScanPartition;
 class _dbScanPartition;
 template <class T>
 class dbTable;
-class _dbScanList;
 class dbScanPin;
 
 class _dbScanChain : public _dbObject
@@ -80,8 +79,6 @@ class _dbScanChain : public _dbObject
   std::string test_mode_name_;
 
   dbTable<_dbScanPartition>* scan_partitions_;
-
-  dbTable<_dbScanList>* scan_lists_;
 };
 dbIStream& operator>>(dbIStream& stream, _dbScanChain& obj);
 dbOStream& operator<<(dbOStream& stream, const _dbScanChain& obj);