How the-openroad-project/opendb works
1. What this repo is
OpenDB is a C++98 physical-design database library for chip layout data. It is not an application with one monolithic runtime; it is a reusable core library plus parsers, writers, language bindings, and tests.
2. Main architectural boundary: public API vs internal implementation
The public surface is in include/opendb, especially db.h, dbTypes.h, and related headers. The implementation lives mainly in src/db, where each public object such as dbInst or dbNet has a corresponding private storage class and table-backed representation.
3. Core data model
The central runtime objects are dbDatabase, dbChip, dbBlock, dbTech, and dbLib. These model the chip, its top-level design, technology rules, and standard-cell libraries. All objects carry persistent object IDs, so references survive save/restore cycles.
4. Storage and object layout
Internal objects are stored in paged tables rather than as individually allocated nodes. That design choice affects the whole architecture: iteration is table-based, IDs are table indices, and the database favors compact, persistent in-memory state over pointer-rich graph structures.
5. Primary input flow: LEF and DEF ingestion
The repo has dedicated readers for LEF and DEF in src/lefin and src/defin, backed by parser implementations in src/lef and src/def. LEF is used to build technology and library data; DEF is used to populate a design block, instances, nets, placements, routes, and physical constraints.
6. Primary output flow: LEF and DEF generation
The inverse path is handled by src/lefout and src/defout, which serialize the database back to the text formats. This round-trip capability is a major architectural feature: parse, edit in memory, and emit again with minimal loss of structure.
7. Binary persistence and exact restore
OpenDB also supports a binary save/restore path, called out in the README as faster than text LEF/DEF. This is important architecturally because the database is designed to be checkpointable and restorable with stable object IDs, enabling exact diffs and reproducible state recovery.
8. Routing and connectivity subsystem
Net routing is represented with specialized structures such as dbWire, dbWireCodec, dbWireGraph, dbRtTree, dbRtNode, and dbRtEdge. This subsystem encodes DEF-style routed geometry as a compact wire representation rather than as a general-purpose graph store.
9. Geometry and physical-shape subsystem
Layout primitives such as boxes, polygons, shapes, transforms, vias, layers, grids, rows, and track grids are spread across many db* classes. This is the physical geometry boundary of the database: it stores coordinates and topology, but not higher-level tool-specific spatial indexes.
10. Technology and rule modeling
dbTech, dbTechLayer, dbTechVia, spacing/min-cut/antenna/same-net rules, and non-default rules model manufacturing constraints and technology metadata. This is where LEF technology semantics become database objects consumed by downstream tools.
11. Language bindings and tool integration
src/swig/python and src/swig/tcl generate Python and Tcl bindings over the same C++ database API. These bindings are thin integration layers; they do not introduce a separate model, they expose the same underlying database objects to scripts and EDA tool flows.
12. Code generation and schema-driven internals
src/codeGenerator indicates that part of the private implementation is generated from a schema (schema.json) rather than hand-written entirely. That means some of the database class boilerplate and implementation structure is mechanically produced, reinforcing the split between stable public API and generated/private internals.
13. Validation, regression, and diffing
The repository includes C++ unit tests, Python tests, Tcl tests, and format regression data under tests/. There are also diff utilities in the LEF/DEF tooling and dbDiff, which support the “exact state” philosophy of the database.
14. Build and delivery environment
The project is built with CMake, with CI and packaging scripts for Jenkins and Docker. Those are infrastructure concerns around the library, not core runtime components, but they matter because the repo is intended to be built into native tools and language bindings.
15. How to draw the architecture
A good diagram should center on dbDatabase as the hub, with inbound arrows from LEF/DEF readers, outbound arrows to LEF/DEF writers and binary persistence, and side arrows to Tcl/Python bindings and test tooling. Around the hub, separate the technology/library model, block/layout model, and routing/wire model as the main internal subsystems.
Main entry points: dbBlock.h Block Model · CMakeLists.txt Build System · db.h DB API · dbDatabase.h Database
Components 23
Public API
Stable C++ headers that define the library surface.
Core DB
Persistent database objects, storage, and internal model.
- Database · Top-level persistent database that anchors the object model.
src/db/dbDatabase.h - Chip Model · Represents the chip and contains the top-level design block.
src/db/dbChip.h - Block Model · Design block containing instances, nets, placement, and routing state.
src/db/dbBlock.h - Tech Model · Technology object holding layers, vias, and manufacturing rules.
src/db/dbTech.h - Lib Model · Standard-cell and macro library objects referenced by the design.
src/db/dbLib.h - Object Tables · Paged-table internals and object ID plumbing used by all db objects.
src/db/dbObject.cpp - Geometry · Boxes, shapes, transforms, vias, rows, grids, and related layout primitives.
src/db/dbShape.cpp - Wire Model · Compact routed-wire representation for nets and DEF geometry.
src/db/dbWire.h - Route Tree · Route-tree codec and graph structures for routed connectivity.
src/db/dbRtTree.cpp - Binary Persist · Binary checkpoint and restore path for fast exact state recovery.
src/db/dbStream.cpp - Codegen · Generates private implementation scaffolding from the schema.
src/codeGenerator/schema.json
Format IO
LEF/DEF readers and writers around the database.
- LEF In · LEF reader path that populates technology and library data.
src/lefin/lefin.cpp - DEF In · DEF reader path that populates blocks, instances, nets, and routing.
src/defin/defin.cpp - LEF Out · Serializes technology and library data back to LEF.
src/lefout/lefout.cpp - DEF Out · Serializes design state back to DEF.
src/defout/defout.cpp
Bindings
Python and Tcl exposure over the same C++ API.
Validation
Regression and unit coverage for core behavior and round-trips.
- C++ Tests · Native tests covering core objects, geometry, callbacks, and wire logic.
src/db/test/test_wire.cpp - Python Tests · Python integration tests for read/write and edit flows.
tests/python/05-read_def_test.py - Tcl Tests · Tcl integration tests for read/write and database access.
tests/tcl/05-read_def_test.tcl
Build
Project, CI, and packaging infrastructure.
- Build System · CMake project plus CI and packaging scripts.
CMakeLists.txt
Connections 31
- DB API → Database: declares · Public API exposes the database entry point.
- DB API → DB Types: shares types · Common enums and identifiers underpin the API.
- Database → Chip Model: owns · Database anchors the chip-level design model.
- Chip Model → Block Model: contains · Chip contains the top-level block/design.
- Block Model → Lib Model: references · Block objects refer to library masters and cells.
- Block Model → Tech Model: uses rules · Block state is constrained by technology definitions.
- Database → Object Tables: stores as tables · Persistent objects are table-backed and ID-addressed.
- Object Tables → Geometry: backs · Geometry primitives are represented by table-stored objects.
- Block Model → Wire Model: contains nets · Design connectivity is represented through wire objects.
- Wire Model → Route Tree: encodes · Route tree structures support compact routed connectivity.
- Tech Model → Geometry: defines layers · Technology rules are tied to geometric layers and vias.
- LEF In → Tech Model: populates · LEF ingestion builds technology objects and layer rules.
- LEF In → Lib Model: populates · LEF ingestion creates library and macro data.
- DEF In → Block Model: populates · DEF ingestion fills the design block with layout state.
- DEF In → Wire Model: populates · DEF ingestion reconstructs routed nets and wires.
- LEF Out → Tech Model: reads · LEF output serializes technology and library state.
- LEF Out → Lib Model: reads · LEF output emits macro/library information.
- DEF Out → Block Model: reads · DEF output serializes the design block state.
- DEF Out → Wire Model: reads · DEF output emits routed connectivity and geometry.
- Binary Persist → Database: checkpoints · Binary save/restore preserves the full database state.
- Codegen → Object Tables: generates · Schema-driven generation produces private implementation scaffolding.
- Python → DB API: wraps · Python exposes the same public C++ API.
- Tcl → DB API: wraps · Tcl exposes the same public C++ API.
- C++ Tests → DB API: verifies · C++ tests exercise core API and implementation behavior.
- Python Tests → Python: verifies · Python tests validate the binding and round-trip flows.
- Tcl Tests → Tcl: verifies · Tcl tests validate the binding and round-trip flows.
- Build System → LEF In: builds · Build system compiles the ingestion tooling.
- Build System → DEF In: builds · Build system compiles the ingestion tooling.
- Build System → Python: builds · Build system produces Python bindings.
- Build System → Tcl: builds · Build system produces Tcl bindings.
- Build System → C++ Tests: runs · CI and scripts execute native test suites.