ODB: read DEF file from ChipletInst in 3DBlox (#10077)

Per the 3DBlox standard (sec 4.3.1) the DEF file is associated with a ChipletInst (in the .3dbx) rather than the ChipletDef. Read it from either location (whichever exists) onto the master chiplet block.

- Add defin::THREE_D_BLOX mode: reads a DEF onto an already-existing block, find-or-creating COMPONENTS/PINS/NETS and deduplicating data shared with the bump map (a bump may appear in both the bmap and the DEF) instead of erroring or duplicating.
- 3dblox: create block+bumps eagerly at .3dbv time; read each chiplet's DEF once (chips_with_def_); error (ODB-547) when two instances of the same chiplet each carry a DEF.
- Writers: emit def_file on a single ChipletInst in the .3dbx (no longer in the .3dbv), chosen deterministically by name; sort the 3dbv LEF_file output for determinism.

Signed-off-by: Jorge Ferreira <jorge.ferreira@precisioninno.com>

Author: jorge-ferreira-pii

src/odb/include/odb/3dblox.h

@@ -53,6 +53,7 @@ class ThreeDBlox
   void createRegion(const ChipletRegion& region, dbChip* chip);
   dbChip* createDesignTopChiplet(const DesignDef& design);
   void createChipInst(const ChipletInst& chip_inst);
+  void readDefForChip(dbChip* chip, const std::string& def_file);
   void createConnection(const Connection& connection);
   void createBump(const BumpMapEntry& entry, dbChipRegion* chip_region);
   std::pair<dbInst*, dbBTerm*> createBump(const BumpMapEntry& entry,
@@ -69,5 +70,13 @@ class ThreeDBlox
   std::unordered_set<odb::dbTech*> written_techs_;
   std::unordered_set<odb::dbLib*> written_libs_;
   std::unordered_set<std::string> read_files_;
+  // Master chips for which a chiplet instance has already supplied a DEF file.
+  // Used to reject two instances of the same chiplet that each carry a DEF,
+  // since they would write design data onto the same shared master block.
+  std::unordered_set<odb::dbChip*> insts_with_def_;
+  // Master chips whose design DEF has already been read. The DEF may be given
+  // by the chiplet definition (3dbv) and/or a chiplet instance (3dbx); it is
+  // read only once per chip so shared DEF data is not duplicated.
+  std::unordered_set<odb::dbChip*> chips_with_def_;
 };
 }  // namespace odb

src/odb/include/odb/defin.h

@@ -25,10 +25,14 @@ class defin
  public:
   enum MODE
   {
-    DEFAULT,     // creates db from scratch (from def)
-    FLOORPLAN,   // update existing COMPONENTS PINS DIEAREA TRACKS ROWS NETS
-                 // SNETS
-    INCREMENTAL  // update existing COMPONENTS PINS
+    DEFAULT,      // creates db from scratch (from def)
+    FLOORPLAN,    // update existing COMPONENTS PINS DIEAREA TRACKS ROWS NETS
+                  // SNETS
+    INCREMENTAL,  // update existing COMPONENTS PINS
+    THREE_D_BLOX  // read DEF onto an existing 3DBlox block (created when the
+                  // chiplet definition was read); find-or-create
+                  // COMPONENTS/PINS/NETS and dedup data shared with the bump
+                  // map
   };
   defin(dbDatabase* db, utl::Logger* logger, MODE mode = DEFAULT);
   ~defin();
@@ -42,8 +46,9 @@ class defin
   void continueOnErrors();
   void useBlockName(const char* name);
 
-  /// Create a new chip
-  void readChip(std::vector<dbLib*>& search_libs,
+  /// Read a DEF onto a chip. Returns true on success, false if the DEF file
+  /// could not be read.
+  bool readChip(std::vector<dbLib*>& search_libs,
                 const char* def_file,
                 dbChip* chip,
                 bool issue_callback = true);

src/odb/src/3dblox/3dblox.cpp

@@ -453,19 +453,6 @@ void ThreeDBlox::createChiplet(const ChipletDef& chiplet)
         db_, tech, chiplet.name, getChipType(chiplet.type, logger_));
   }
 
-  // Read DEF file
-  if (!chiplet.external.def_file.empty()) {
-    odb::defin def_reader(db_, logger_, odb::defin::DEFAULT);
-    std::vector<odb::dbLib*> search_libs;
-    for (odb::dbLib* lib : db_->getLibs()) {
-      search_libs.push_back(lib);
-    }
-    // No callbacks here as we are going to give one postRead3Dbx later
-    def_reader.readChip(search_libs,
-                        chiplet.external.def_file.c_str(),
-                        chip,
-                        /*issue_callback*/ false);
-  }
   const int dbu_per_micron = db_->getDbuPerMicron();
   if (chiplet.design_width != -1.0) {
     chip->setWidth(std::round(chiplet.design_width * dbu_per_micron));
@@ -515,6 +502,35 @@ void ThreeDBlox::createChiplet(const ChipletDef& chiplet)
   for (const auto& [_, region] : chiplet.regions) {
     createRegion(region, chip);
   }
+
+  // Read the DEF file (if any) onto the block created above. The block and its
+  // bumps already exist, so the read uses the 3DBlox defin mode, which
+  // find-or-creates and dedups data shared with the bump map instead of
+  // erroring because a block is already present.
+  if (!chiplet.external.def_file.empty()) {
+    readDefForChip(chip, chiplet.external.def_file);
+  }
+}
+
+void ThreeDBlox::readDefForChip(dbChip* chip, const std::string& def_file)
+{
+  // A chiplet's design DEF only needs to be read once. The DEF may be supplied
+  // by the chiplet definition (3dbv) and/or by a chiplet instance (3dbx); if it
+  // was already read onto this chip, skip it so that DEF data not shared with
+  // the bump map (rows, tracks, ...) is not duplicated.
+  if (chips_with_def_.contains(chip)) {
+    return;
+  }
+  odb::defin def_reader(db_, logger_, odb::defin::THREE_D_BLOX);
+  std::vector<odb::dbLib*> search_libs;
+  search_libs.assign(db_->getLibs().begin(), db_->getLibs().end());
+  // No callbacks here as we are going to give one postRead3Dbx later. Mark the
+  // chip only on success so a failed read (e.g. bad path) does not suppress a
+  // later valid DEF for the same chip.
+  if (def_reader.readChip(
+          search_libs, def_file.c_str(), chip, /*issue_callback*/ false)) {
+    chips_with_def_.insert(chip);
+  }
 }
 
 static dbChipRegion::Side getChipRegionSide(const std::string& side,
@@ -698,6 +714,21 @@ void ThreeDBlox::createChipInst(const ChipletInst& chip_inst)
       static_cast<int>(std::round(chip_inst.loc.y * dbu_per_micron)),
       static_cast<int>(std::round(chip_inst.z * dbu_per_micron)),
   });
+
+  // Per the 3DBlox standard, the DEF file may be associated with the chiplet
+  // instance (ChipletInst.external) rather than the chiplet definition. Read it
+  // onto the referenced master chip's block. The DEF is shared design data, so
+  // two instances of the same chiplet may not each carry their own DEF.
+  if (!chip_inst.external.def_file.empty()) {
+    if (!insts_with_def_.insert(chip).second) {
+      logger_->error(utl::ODB,
+                     547,
+                     "3DBX Parser Error: There can't be 2 instances of the "
+                     "same chiplet {} with a def file each",
+                     chip_inst.reference);
+    }
+    readDefForChip(chip, chip_inst.external.def_file);
+  }
 }
 static std::vector<std::string> splitPath(const std::string& path)
 {

src/odb/src/3dblox/dbvWriter.cpp

@@ -3,13 +3,14 @@
 
 #include "dbvWriter.h"
 
+#include <algorithm>
 #include <filesystem>
 #include <string>
 #include <unordered_set>
+#include <vector>
 
 #include "baseWriter.h"
 #include "odb/db.h"
-#include "odb/defout.h"
 #include "utl/Logger.h"
 #include "yaml-cpp/yaml.h"
 namespace odb {
@@ -177,9 +178,8 @@ void DbvWriter::writeExternal(YAML::Node& external_node, odb::dbChip* chiplet)
 {
   if (chiplet->getChipType() != odb::dbChip::ChipType::HIER) {
     writeLef(external_node, chiplet);
-    if (chiplet->getBlock() != nullptr) {
-      writeDef(external_node, chiplet);
-    }
+    // Per the 3DBlox standard the DEF file is attached to a chiplet instance,
+    // so it is emitted in the .3dbx (by the DbxWriter), not here in the .3dbv.
     if (auto prop = odb::dbStringProperty::find(chiplet, "verilog_file")) {
       external_node["verilog_file"] = prop->getValue();
     }
@@ -223,21 +223,18 @@ void DbvWriter::writeLef(YAML::Node& external_node, odb::dbChip* chiplet)
     YAML::Node list_node;
     list_node.SetStyle(YAML::EmitterStyle::Flow);
     external_node["LEF_file"] = list_node;
+    // Sort so the output is deterministic regardless of the (unordered) set
+    // iteration order.
+    std::vector<std::string> lef_files;
+    lef_files.reserve(libs.size());
     for (auto lib : libs) {
-      std::string lef_file = std::string(lib->getName()) + "_lib.lef";
+      lef_files.push_back(std::string(lib->getName()) + "_lib.lef");
+    }
+    std::ranges::sort(lef_files);
+    for (const auto& lef_file : lef_files) {
       external_node["LEF_file"].push_back(lef_file);
     }
   }
 }
 
-void DbvWriter::writeDef(YAML::Node& external_node, odb::dbChip* chiplet)
-{
-  std::string def_file = std::string(chiplet->getName()) + ".def";
-  std::string def_file_path = current_dir_path_ + def_file;
-  odb::DefOut def_writer(logger_);
-  auto block = chiplet->getBlock();
-  def_writer.writeBlock(block, def_file_path.c_str());
-  external_node["DEF_file"] = def_file;
-}
-
 }  // namespace odb

src/odb/src/3dblox/dbvWriter.h

@@ -37,7 +37,6 @@ class DbvWriter : public BaseWriter
   void writeRegion(YAML::Node& region_node, odb::dbChipRegion* region);
   void writeExternal(YAML::Node& external_node, odb::dbChip* chiplet);
   void writeLef(YAML::Node& external_node, odb::dbChip* chiplet);
-  void writeDef(YAML::Node& external_node, odb::dbChip* chiplet);
 };
 
 }  // namespace odb

src/odb/src/3dblox/dbxWriter.cpp

@@ -3,11 +3,14 @@
 
 #include "dbxWriter.h"
 
+#include <filesystem>
 #include <string>
+#include <unordered_map>
 #include <vector>
 
 #include "baseWriter.h"
 #include "odb/db.h"
+#include "odb/defout.h"
 #include "odb/geom.h"
 #include "utl/Logger.h"
 #include "yaml-cpp/yaml.h"
@@ -21,6 +24,10 @@ DbxWriter::DbxWriter(utl::Logger* logger, odb::dbDatabase* db)
 
 void DbxWriter::writeChiplet(const std::string& filename, odb::dbChip* chiplet)
 {
+  auto path = std::filesystem::path(filename);
+  if (path.has_parent_path()) {
+    current_dir_path_ = path.parent_path().string() + "/";
+  }
   YAML::Node root;
   writeYamlContent(root, chiplet);
   writeYamlToFile(filename, root);
@@ -56,17 +63,49 @@ void DbxWriter::writeDesign(YAML::Node& design_node, odb::dbChip* chiplet)
 void DbxWriter::writeChipletInsts(YAML::Node& instances_node,
                                   odb::dbChip* chiplet)
 {
+  // The DEF is master (design) data shared by all instances of a chiplet, so it
+  // is emitted for exactly one instance per master chiplet. Choose that
+  // instance deterministically as the one with the smallest name.
+  std::unordered_map<odb::dbChip*, std::string> def_inst_by_master;
+  for (auto inst : chiplet->getChipInsts()) {
+    odb::dbChip* master = inst->getMasterChip();
+    if (master->getBlock() == nullptr) {
+      continue;
+    }
+    const std::string& name = inst->getName();
+    auto it = def_inst_by_master.find(master);
+    if (it == def_inst_by_master.end() || name < it->second) {
+      def_inst_by_master[master] = name;
+    }
+  }
+
   for (auto inst : chiplet->getChipInsts()) {
     YAML::Node instance_node = instances_node[std::string(inst->getName())];
-    writeChipletInst(instance_node, inst);
+    auto it = def_inst_by_master.find(inst->getMasterChip());
+    const bool write_def
+        = it != def_inst_by_master.end() && it->second == inst->getName();
+    writeChipletInst(instance_node, inst, write_def);
   }
 }
 
 void DbxWriter::writeChipletInst(YAML::Node& instance_node,
-                                 odb::dbChipInst* inst)
+                                 odb::dbChipInst* inst,
+                                 bool write_def)
 {
-  auto master_name = inst->getMasterChip()->getName();
-  instance_node["reference"] = master_name;
+  odb::dbChip* master = inst->getMasterChip();
+  instance_node["reference"] = master->getName();
+
+  // Per the 3DBlox standard the DEF file is attached to a chiplet instance.
+  // Dump the master block to a DEF and reference it from a single instance of
+  // each master chiplet.
+  if (write_def) {
+    std::string def_file = std::string(master->getName()) + ".def";
+    odb::DefOut def_writer(logger_);
+    def_writer.writeBlock(master->getBlock(),
+                          (current_dir_path_ + def_file).c_str());
+    YAML::Node external_node = instance_node["external"];
+    external_node["def_file"] = def_file;
+  }
 }
 
 void DbxWriter::writeStack(YAML::Node& stack_node, odb::dbChip* chiplet)

src/odb/src/3dblox/dbxWriter.h

@@ -34,7 +34,9 @@ class DbxWriter : public BaseWriter
   void writeDesign(YAML::Node& design_node, odb::dbChip* chiplet);
   void writeDesignExternal(YAML::Node& external_node, odb::dbChip* chiplet);
   void writeChipletInsts(YAML::Node& instances_node, odb::dbChip* chiplet);
-  void writeChipletInst(YAML::Node& instance_node, odb::dbChipInst* inst);
+  void writeChipletInst(YAML::Node& instance_node,
+                        odb::dbChipInst* inst,
+                        bool write_def);
   void writeStack(YAML::Node& stack_node, odb::dbChip* chiplet);
   void writeStackInstance(YAML::Node& stack_instance_node,
                           odb::dbChipInst* inst);

src/odb/src/defin/defin.cpp

@@ -66,13 +66,13 @@ void defin::useBlockName(const char* name)
   reader_->useBlockName(name);
 }
 
-void defin::readChip(std::vector<dbLib*>& libs,
+bool defin::readChip(std::vector<dbLib*>& libs,
                      const char* def_file,
                      dbChip* chip,
                      const bool issue_callback)
 {
   absl::MutexLock lock(&def_mutex_);
-  reader_->readChip(libs, def_file, chip, issue_callback);
+  return reader_->readChip(libs, def_file, chip, issue_callback);
 }
 
 }  // namespace odb

src/odb/src/defin/definComponent.cpp

@@ -136,14 +136,33 @@ void definComponent::begin(const char* iname, const char* mname)
     _errors++;
     return;
   }
-  if (_mode != defin::DEFAULT) {
+  if (_mode == defin::FLOORPLAN || _mode == defin::INCREMENTAL) {
     _cur_inst = _block->findInst(iname);
     if (_cur_inst == nullptr) {
       _errors++;
       return;
     }
     _update_cnt++;
   } else {
+    // DEFAULT and THREE_D_BLOX create the instance. THREE_D_BLOX first looks
+    // for an existing instance (e.g. a bump already created from the bump map)
+    // and reuses it instead of erroring on a duplicate definition.
+    if (_mode == defin::THREE_D_BLOX) {
+      _cur_inst = _block->findInst(iname);
+      if (_cur_inst != nullptr) {
+        if (_cur_inst->getMaster() != master) {
+          _logger->warn(utl::ODB,
+                        549,
+                        "3DBlox DEF component {} reuses an existing instance "
+                        "with master {} but the DEF specifies master {}.",
+                        iname,
+                        _cur_inst->getMaster()->getName(),
+                        master->getName());
+        }
+        _update_cnt++;
+        return;
+      }
+    }
     _cur_inst = dbInst::create(_block, master, iname);
     if (_cur_inst != nullptr) {
       _inst_cnt++;

src/odb/src/defin/definPin.cpp

@@ -43,11 +43,40 @@ void definPin::pinBegin(const char* name, const char* net_name)
   const char* s = strstr(name, ".extra");
 
   if (s == nullptr) {
-    if (_mode != defin::DEFAULT) {
+    if (_mode == defin::FLOORPLAN || _mode == defin::INCREMENTAL) {
       _cur_bterm = _block->findBTerm(name);
       if (_cur_bterm != nullptr) {
         _update_cnt++;
       }
+    } else if (_mode == defin::THREE_D_BLOX) {
+      // Find-or-create: a bump may have already created this bterm (and its
+      // net) from the bump map, so reuse it instead of duplicating it.
+      _cur_bterm = _block->findBTerm(name);
+      if (_cur_bterm != nullptr) {
+        _update_cnt++;
+        // Make the DEF authoritative for the reused pin: connect it to the
+        // net named by this PIN (idempotent if already the same net) and drop
+        // any shapes created earlier (e.g. from the bump map) so the DEF's
+        // port geometry is not duplicated.
+        dbNet* existing_net = _cur_bterm->getNet();
+        if (existing_net != nullptr && existing_net != net) {
+          _logger->warn(utl::ODB,
+                        548,
+                        "3DBlox DEF reconnects pin {} from net {} to net {}.",
+                        name,
+                        existing_net->getName(),
+                        net->getName());
+        }
+        _cur_bterm->connect(net);
+        std::vector<dbBPin*> old_bpins(_cur_bterm->getBPins().begin(),
+                                       _cur_bterm->getBPins().end());
+        for (dbBPin* bpin : old_bpins) {
+          dbBPin::destroy(bpin);
+        }
+      } else {
+        _cur_bterm = dbBTerm::create(net, name);
+        _bterm_cnt++;
+      }
     } else {
       _cur_bterm = dbBTerm::create(net, name);
       _bterm_cnt++;