Tool Philosophy#

OpenROAD is a tool to build a chip from synthesizable RTL (Verilog) tocompleted physical layout (manufacturable, tapeout-clean GDSII).

The unifying principle behind the design of OpenROAD is for all of thetools to reside in one tool, with one process, and one database. Alltools in the flow should use Tcl commands exclusively to control theminstead of external “configuration files”. File-based communicationbetween tools and forking processes is strongly discouraged. Thisarchitecture streamlines the construction of a flexible tool flow andminimizes the overhead of invoking each tool in the flow.

Tool File Organization#

Every tool follows the following file structure, grouping sources, testsand headers together.

• src/This folder contains the source files for individual tools.

• OpenROAD repository:This folder contains the top-level files for overall compilation. OpenROAD usesswig that acts as a wrapper for C/C++ programs to be callable in higher-level languages, such as Python and Tcl.

Some tools such as OpenSTA are submodules, which are simplysubdirectories insrc/ that are pointers to the git submodule. They areintentionally not segregated into a separate module.

The use of submodules for new code integrated into OpenROAD is stronglydiscouraged. Submodules make changes to the underlying infrastructure(e.g., OpenSTA) difficult to propagate across the dependent submodulerepositories.

Where external/third-party code that a tool depends on should be placeddepends on the nature of the dependency.

• Libraries - code packaged as a linkable library. Examples aretcl,boost,zlib,eigen,lemon,spdlog.

These should be installed in the build environment and linked byOpenROAD. Document these dependencies in the top-levelREADME.md file.TheDockerfile should be updated to illustrate where to find the libraryand how to install it. Adding libraries to the build environment requirescoordination with system administrators, so that continuous integration hosts ensurethat environments include the dependency. Advance notificationshould also be given to the development team so that their private buildenvironments can be updated.

Each tool CMake file builds a library that is linked by the OpenROADapplication. The tools should not define amain() function. If thetool is Tcl only and has no C++ code, it does not need to have a CMakefile. Tool CMake files shouldnot include the following:

• cmake_minimum_required

• GCC_COVERAGE_COMPILE_FLAGS

• GCC_COVERAGE_LINK_FLAGS

• CMAKE_CXX_FLAGS

• CMAKE_EXE_LINKER_FLAGS

None of the tools have commands to read or write LEF, DEF, Verilog ordatabase files. For consistency, these functions are all provided by the OpenROADframework.

Tools should package all of their state in a single class. An instance of eachtool class resides in the top-level OpenROAD object. This allowsmultiple tools to exist at the same time. If any tool keeps state inglobal variables (even static), then only one tool can exist at a time. Manyof the tools being integrated were not built with this goal in mind andwill only work on one design at a time.

Each tool should use a unique namespace for all of its code. The samenamespace should be used for Tcl functions, including those defined by aswig interface file. Internal Tcl commands stay inside the namespace,and user visible Tcl commands should be defined in the global namespace.User commands should be simple Tcl commands such asglobal_placementthat do not create tool instances that must be based to the commands.Defining Tcl commands for a tool class is fine for internal commands, but notfor user visible commands. Commands have an implicit argument of thecurrent OpenROAD class object. Functions to get individual tools fromthe OpenROAD object can be defined.

Initialization (C++ tools only)#

The OpenROAD class has pointers to each tool, with functions to get eachtool. Each tool has (at a minimum) a function to make an instance of thetool class, an initialization function that is called after all ofthe tools have been made, and a function to delete the tool. This smallheader doesnot include the class definition for the tool so thatthe OpenROAD framework does not have to know anything about the toolinternals or include a gigantic header file.

MakeTool.hh defines the following:

Tool*makeTool();voidinitTool(OpenRoad*openroad);voiddeleteTool(Tool*tool);

TheOpenRoad::init() function calls all of themakeTool functions andthen all of theinitTool() functions. Theinit functions are called fromthe bottom of the tool dependencies. Eachinit function grabs the stateit needs out of theOpenRoad instance.

Commands#

Tools should provide Tcl commands to control them. Tcl object based toolinterfaces are not user-friendly. Define Tcl procedures that takekeyword arguments that reference theOpenRoad object to get tool state.OpenSTA has Tcl utilities to parse keyword arguments(sta::parse_keyword_args). SeeOpenSTA/tcl/*.tcl forexamples. Use swig to define internal functions to C++ functionality.

Tcl files can be included by encoding them in CMake into a string thatis evaluated at run time (SeeResizer::init()).

Errors#

Tools should report errors to the user using theord::error functiondefined ininclude/openroad/Error.hh.ord::error throwsord::Exception. The variablesord::exit_on_error andord::file_continue_on_error control how the error is handled. Iford::exit_on_error istrue then OpenROAD reports the error and exits. Ifthe error is encountered while reading a file with thesource orread_sdc commands andord::file_continue_on_error isfalse then noother commands are read from the file. The default value isfalse for bothvariables.

Test#

Each “tool” has a/test directory containing a script namedregression to run “unit” tests. With no arguments it should rundefault unit tests.

No database files should be in tests. Read LEF/DEF/Verilog to make adatabase.

The regression script should not depend on the current workingdirectory. It should be able to be run from any directory. Use filenamesrelative to the script name rather the current working directory.

Regression scripts should print a concise summary of test failures. Theregression script should return an exit code of 0 if there are noerrors and 1 if there are errors. The script shouldnot printthousands of lines of internal tool information.

Regression scripts should pass the-no_init option toopenroad so thata user’sinit file is not sourced before the tests runs.

Regression scripts should add output files or directories to.gitignore so that running does not leave the source repository“dirty”.

The Nangate45 open-source library data used by many tests is intest/Nangate45. Use the following command to add a link in the tool command:

cdsrc/<tool>/testln-s../../../test/Nangate45

After the link is installed, the test script can read the Liberty filewith the command shown below.

read_libertyNangate45/Nangate45_typ.lib

Building#

Instructions for building are availablehere.

Example of Adding a Tool to OpenROAD#

The directoryOpenRoad/src/exampleillustrates a tool named “Example” that uses the file structure described above.It defines a command to run the tool as illustrated below:

>example_instance-nametest[INFOEXA-0001]Makinganexampleinstancenamedtest>helpexample_instanceexample_instance[-namename]

The example include TCL & Python APIs with unit tests. Also demonstrated is how to create debug graphics for algorithm visualization. Runningopenroad-guibasic.tcl insrc/exa/test will demonstrate the capability.

Documentation#

Tool commands should be documented in the top-level OpenROADREADME.mdfile. Detailed documentation should be thetool/README.md file.

Tool Flow Namespace#

Tool namespaces are usually three-lettered lowercase letters.

• Verilog to DB (dbSTA)

• OpenDB: Open Database (odb)

• TritonPart: constraints-driven paritioner (par)

• Floorplan Initialization (ifp)

• ICeWall chip-level connections (pad)

• I/O Placement (ppl)

• PDN Generation (pdn)

• Tapcell and Welltie Insertion (tap)

• Macro Placer (mpl)

• RePlAce Global Placer (gpl)

• Gate resizing and buffering (rsz)

• Parasitics estimation (est)

• Detailed placement (dpl)

• Clock tree synthesis (cts)

• FastRoute Global routing (grt)

• Antenna check and diode insertion (ant)

• TritonRoute Detailed routing (drt)

• Metal fill insertion (fin)

• Design for Test (dft)

• OpenRCX Parasitic Extraction (rcx)

• OpenSTA timing/power analyzer (sta)

• Graphical User Interface (gui)

• Static IR analyzer (psm)

• Example tool (exa)

Tool Checklist#

Tools should make every attempt to minimize external dependencies.Linking libraries other than those currently in use complicates thebuilds and sacrifices the portability of OpenROAD. OpenROAD should beportable to many different compiler/operating system versions anddependencies make this vastly more complicated.

1. OpenROAD submodules reference toolopenroad branch head. No gitdevelop,openroad_app, oropenroad_build branches.

2. Submodules used by more than one tool belong insrc/, not duplicated in each tool repo.

3. CMakeLists.txt does not use add_compile_options include_directories link_directories link_libraries. Use target_ versions instead. See tipshere.

4. CMakeLists.txt does not use glob. Use explicit lists of source files and headers instead.

5. CMakeLists.txt does not defineCFLAGSCMAKE_CXX_FLAGSCMAKE_CXX_FLAGS_DEBUGCMAKE_CXX_FLAGS_RELEASE. Let the top level and defaults control these.

6. Nomain.cpp or main procedure.

7. No compiler warnings for GCC or Clang with optimization enabled.

8. Does not callflute::readLUT (called once byopenroad).

9. Tcl command(s) documented in top levelREADME.md in flow order.

10. Command line tool documentation in tool README.

11. Conforms to Tcl command naming standards (no camel case).

12. Does not read configuration files. Use command arguments or support commands.

13. .clang-format at tool root directory to aid foreign programmers.

14. Nojenkins/,Jenkinsfile,Dockerfile in tool directory.

15. regression script namedtest/regression with no arguments that runs tests. Nottests/regression-tcl.sh, nottest/run_tests.py etc.

16. regression script should run independent of current directory. For example,../test/regression should work.

17. regression should only print test results or summary, not belch 1000s of lines of output.

18. Test scripts use OpenROAD tcl commands (notitcl, not internal accessors).

19. regression script should only write files in a directory that is in the tool’s.gitignore so the hierarchy does not have modified files in it as a result or running the regressions.

20. Regressions report no memory errors withvalgrind (stretch goal).

21. Regressions report no memory leaks withvalgrind (difficult).

22. Ensure the top-level README and Tcl format are compliant.

Code Linting and Formatting#

OpenROAD uses bothclang-tidy andclang-format to perform automatic linting and formatting whenever a pull request is submitted. To run these locally, please first setup Clang Tooling using thisguide. Thereafter, you may run these commands:

cmake.-Bbuild# generate build files# typically only run these commands on files you changed.clang-tidy-p./buildsource_file.cppclang-format-i-style=file:.clang-formatsource_file.cpp

To runclang-tidy on all files, you can use the following script that runsclang-tidy in parallel and also caches the results, so subsequent runsonly have to operate on changed files.

cmake.-Bbuild# generate build filesln-sfbuild/compile_commands.json.# make compilation db visible/bin/shetc/run-clang-tidy-cached.cc

Doxygen#

OpenROAD uses Doxygen style comments to generate documentation.See the generated documentationhere.Our preferred syntax for Doxygen comments can be found in thisfile. Also, do refer to the official Doxygendocumentation for more information on what you can include in your Doxygencommentshere.

Below shows an example snippet taken from./src/odb/include/odb/db.h:

////// dbProperty - Int property.///classdbIntProperty:publicdbProperty{public:/// Get the value of this property.intgetValue();/// Set the value of this property.voidsetValue(intvalue);/// Create a int property. Returns nullptr if a property with the same name/// already exists.staticdbIntProperty*create(dbObject*object,constchar*name,intvalue);/// Find the named property of type int. Returns nullptr if the property does/// not exist.staticdbIntProperty*find(dbObject*object,constchar*name);};

Guidelines#

1. Internally, the code should useint for all database units andint64_tfor all area calculations. Refer to thislink for a moredetailed writeup on the reasons why this approach is preferred. The onlyplace that the database distance units should appear in any programshould be in the user interface, as microns are easier for humans than DBUs.