9_adding_a_tool_example

◀️   Previous: Machine Learning Example

ClipGraphExtract

Contributed by: Mingyu Woo

• An example repo for adding a tool to the top-level app and using an OpenDB-C++ API for.
• The base sources are copied from OpenROAD repo, commit: 7156dc. Unessential repos are removed to be compiled well in other environments.
• Please read the doc/OpenRoadArch.md to understand the requirement. The ClipGraphExtract follows the OpenRoadArch.md manual.

ClipGraphExtract Flow

Clique and star net decomposition example

• In OpenROAD app, read_lef and read_def command will populate the OpenDB's data structure.
• Using OpenDB's C++ API, save all instances' bbox to Boost/RTree structure.
• Send a region query to RTree to extract related instances using the clips' coordinates.
• Generate clip graph's clique/star net models as text file (e.g. edges list) for graph neural network models.

File Structure

• include/openroad/

  • public headers location of OpenROAD.

• src/

  • OpenROAD source code files. The tools source code should be located here.

• src/ClipGraphExtractor/src/

  • source code location of ClipGraphExtractor.

• src/ClipGraphExtractor/include/clip_graph_ext/

  • public headers location of ClipGraphExtractor.

Implementation Details

OpenDB C++ API

• All the OpenDB reference is in the OpenDB's public header (OpenDB/include/opendb/db.h). Please check this header file first to understand how the structures are designed.

• Set the OpenDB pointer from Top-level app (Link)

  void 
  initClipGraphExtractor(OpenRoad *openroad) 
  {
    Tcl_Interp* tcl_interp = openroad->tclInterp();
    Clipgraphextractor_Init(tcl_interp);
    sta::evalTclInit(tcl_interp, sta::graph_extractor_tcl_inits);
    openroad->getClipGraphExtractor()->setDb(openroad->getDb());
    openroad->getClipGraphExtractor()->setSta(openroad->getSta());
  }
  

• Push instances' location to RTree using dbInst* (Link)

  dbBlock* block = db_->getChip()->getBlock();
  for( dbInst* inst : block->getInsts() ) {
    dbBox* bBox = inst->getBBox();
    box b (point(bBox->xMin(), bBox->yMin()), 
            point(bBox->xMax(), bBox->yMax()));
    rTree->insert( make_pair(b, inst) );
  }
  

• Send region query using given bbox coordinates. (Link)

  box queryBox( point(lx, ly), point(ux, uy) );
  
  vector<value> foundInsts; 
  rTree->query(bgi::intersects(queryBox), 
      std::back_inserter(foundInsts));
  
  cout << "NumFoundInsts: " << foundInsts.size() << endl;
  

• Store distinctive instances into hash_set (e.g. std::set<dbInst*>) (Link)

  set<odb::dbInst*> instSet;
  for(value& val : foundInsts) {
    odb::dbInst* inst = val.second;
    instSet.insert( inst ); 
  }
  

• Extract distinctive dbITerms from dbInst objects (Link)

  for(odb::dbITerm* iTerm : inst->getITerms()) {
    if( iTerm->getSigType() == odb::dbSigType::POWER ||
        iTerm->getSigType() == odb::dbSigType::GROUND ) {
      continue;
    }
    iTermSet.insert(iTerm); 
  }
  

• Extract distinctive dbNet from dbITerm objects (Link)

  // extract Net
  set<odb::dbNet*> netSet;
  for(odb::dbITerm* iTerm : iTermSet) {
    odb::dbNet* net = iTerm->getNet();
    if (!net) { 
      continue;
    }
    if( net->getSigType() == odb::dbSigType::POWER ||
        net->getSigType() == odb::dbSigType::GROUND ||
        net->getSigType() == odb::dbSigType::CLOCK ) {
      continue;
    }
    netSet.insert(net);
  }
  

Adding a Tool

• Write tool's CMakeLists.txt (src/ClipGraphExtract/CMakeLists.txt)

• Modify OpenROAD's CMakeLists.txt accordingly (src/CMakeLists.txt)

  • (Link)

    set(CLIP_GRAPHEXT_HOME ${PROJECT_SOURCE_DIR}/src/ClipGraphExtract)
    

  • (Link)

    add_subdirectory(ClipGraphExtract)
    

  • (Link)

    target_link_libraries(openroad
    ...
    ClipGraphExtractor
    ...
    )
    

• Write an initializing public header inside tool (Link)

  namespace ord {
  class OpenRoad;
  
  ClipGraphExtract::ClipGraphExtractor* makeClipGraphExtractor();
  void initClipGraphExtractor(OpenRoad *openroad);
  void deleteClipGraphExtractor(ClipGraphExtract::ClipGraphExtractor *graphext);
  }
  

• Change OpenRoad.cc and OpenRoad.hh accordinly

  • include/openroad/OpenRoad.hh

    // incomplete header
    namespace ClipGraphExtract {
    class ClipGraphExtractor;
    }
    
    ...
    // getter functions
    ClipGraphExtract::ClipGraphExtractor *getClipGraphExtractor() { return clipGraphExt_; }
    ...
    // private variable
    ClipGraphExtract::ClipGraphExtractor *clipGraphExt_;
    

  • src/OpenRoad.cc

    // make
    clipGraphExt_ = makeClipGraphExtractor();
    ...
    // delete
    deleteClipGraphExtractor(clipGraphExt_);
    ...
    // init
    initClipGraphExtractor(this);
    ...
    

• Registering Hidden Tcl Command using SWIG (src/ClipGraphExtract/src/clipGraphExtract.i)

  // Note that hidden SWIG tcl commands must have *_cmd as a function name.
  void
  graph_extract_cmd(int lx, int ly, int ux, int uy) 
  {
    ClipGraphExtractor* graphExt = getClipGraphExtractor();
    graphExt->extract(lx, ly, ux, uy);
  }
  

• Registering Visible Tcl Command using OpenSTA Tcl Template (src/ClipGraphExtract/src/clipGraphExtract.tcl)

  // register graph_extract commands in OpenROAD binary.
  sta::define_cmd_args "graph_extract" {
    [-graph_model star/clique]\
    [-edge_weight_model weight]\
    [-out_file fileName]
  }
  
  // function details
  proc graph_extract { args } {
  ...
  // *_cmd SWIG functions can be used in here.
  ...
  }
  

How to build/test?

• Build

  • Please follow the build manual in OpenROAD

    $ mkdir build
    $ cd build
    $ cmake ..
    $ make
    

• Test on ClipGraphExtract

  $ cd src/ClipGraphExtract/test/
  $ ../../../build/src/openroad test.tcl
  

License

• BSD-3-Clause license.
• Code found under the subdirectory (e.g., src/OpenSTA) have individual copyright and license declarations at each folder.

◀️   Previous: Machine Learning Example