# OpenDBPy
This repository contains only the OpenDB portion of the OpenRoad project. The code and build system has been slightly modified to support standalone building. Python setuptools has been added to allow the code to be converted into a wheel.
You can build and install the module by running:
```
python3 -m pip install . -v
```
# OpenDB
OpenDB is a design database to support tools for physical chip design. It
was originally developed by Athena Design Systems. Nefelus, Inc. acquired
the rights to the code and open-sourced it with BSD-3 license in 2019 to support the DARPA
OpenROAD project.
The structure of OpenDB is based on the text file formats LEF
(library) and DEF (design) formats version 5.6. OpenDB supports a
binary file format to save and load the design much faster than using
LEF and DEF.
OpenDB is written in C++ 98 with standard library style iterators.
The classes are designed to be fast enough to base an application on without
having to copy them into application-specific structures.
## Directory structure
```
include/odb/db.h - public header for all database classes
src/db - private/internal database representations
src/lefin - LEF reader
src/lefout - LEF writer
src/defin - DEF reader
src/defout - DEF writer
```
## Database API
We are still working on documenting the APIs. We have over 1,800 objects
and functions that we are still documenting (for both TCL and Python).
**Contributions are very welcome in this effort**. Find starting points below.
### TCL
After building successfully, run OpenDB Tcl shell using
`../../build/src/odb/src/swig/tcl/odbtcl`. An example usage:
```
set db [dbDatabase_create]
set lef_parser [new_lefin $db true]
set tech [lefin_createTech $lef_parser ./src/odb/test/data/gscl45nm.lef]
```
You can find examples on using the API from Tcl under `test/tcl/` directory.
The full set of the Tcl commands exposed can be found under
`./build/src/swig/tcl/opendb_wrapper.cpp`. Search for `SWIG_prefix`.
### Python
After building successfully, run `openroad -python` to enable the Python
interpreter. You can find examples on using the API from Python under
`test/python/` directory.
To list the full set of the Python classes exposed run `openroad -python`
then:
```
import openroad
import odb
print(', '.join(dir(openroad)))
print(', '.join(dir(odb)))
```
### C++
All public database classes are defined in `db.h`. These class definitions
provide all functions for examining and modifying the database objects. The
database is an object itself, so multiple database objects can exist
simultaneously (no global state).
`dbTypes.h` defines types returned by database class member functions.
All database objects are in the `odb` namespace.
- `dbChip`
- `dbBlock`
- `dbTech`
- `dbLib`
All database objects have a 32bit object identifier accessed with the
`dbObject::getOID` base class member function that returns a `uint`. This
identifier is preserved across save/restores of the database so it should
be used to reference database object by data structures instead of pointers
if the reference lifetime is across database save/restores. OIDs allow the
database to have exactly the same layout across save/restores.
The database distance units are **nanometers** and use the type `uint`.
## Example scripts
## Regression tests
There are a set of regression tests in /test.
```
./test/regression-tcl.sh
./test/regression-py.sh
```
## Database Internals
The internal description included here is paraphrased from Lukas van Ginneken
by James Cherry.
The database separates the implementation from the interface, and as a result,
each class becomes two classes, a public one and a private one. For instance,
`dbInst` has the public API functions, while class `_dbInst` has the private
data fields.
The objects are allocated in dynamically resizable tables, the implementation
of which is in `dbTable.hpp`. Each table consists of a number of pages,
each containing 128 objects. The table contains the body of the `struct`,
not a set of pointers. This eliminates most of the pointer overhead while
iteration is accomplished by stepping through the table. Thus, grouping these
objects does not require a doubly-linked list and saves 16 bytes per object
(at the cost of some table overhead). Each object has an id, which is the
index into the table. The lowest 7 bits are the index in the page, while
the higher bits are the page number. Object id's are persistent when saving
and reading the data model to disk, even as pointer addresses may change.
Everything in the data model can be stored on disk and restored from disk
exactly the way it was. An extensive set of equality tests and diff functions
make it possible to check for even the smallest deviation. The capability
to save an exact copy of the state of the system makes it possible to create
a checkpoint. This is a necessary capability for debugging complex systems.
The code follows the definition of LEF and DEF closely and reflects many of
the idiosyncrasies of LEF and DEF. The code defines many types of objects
to reflect LEF and DEF constructs although it sometimes uses different
terminology, for instance, the object to represent a library cell is called
`dbMaster` while the LEF keyword is MACRO.
The data model supports the EEQ and LEQ keywords (i.e., electrically equivalent
and logically equivalent Masters), which could be useful for sizing. However,
it does not support any logic function representation. In general, there is
very limited support for synthesis-specific information: no way to represent
busses, no way to represent logic function, very limited understanding of
signal flow, limited support of timing information, and no support for high
level synthesis or test insertion.
The db represents routing as in DEF, representing a trace from point to point
with a given width. The layout for a net is stored in a class named `dbWire`
and it requires a special `dbWireDecoder` (which works like an iterator)
to unpack the data and another `dbWireEncoder` to pack it. The data model
does not support a region query and objects that are in the same layer are
scattered about the data model and are of different classes.
This means that whatever tool is using the layout information will have to
build its own data structures that are suitable to the layout operations
of that tool. For instance, the router, the extractor, and the DRC engine
would each have to build their unique data structures. This encourages
batch mode operation (route the whole chip, extract the whole chip, run
DRC on the whole chip).
## Limitations
## FAQs
Check out
[GitHub discussion](https://github.com/The-OpenROAD-Project/OpenROAD/discussions/categories/q-a?discussions_q=category%3AQ%26A+fastroute+in%3Atitle)
about this tool.
## LICENSE
BSD 3-Clause License. See [LICENSE](LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/jonpry/OpenDb",
"name": "OpenROAD-OpenDbPy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "setuptools extension cpp cmake build package pypi bindings swig pybind11",
"author": "Jon Pry",
"author_email": "jonpry@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/35/42/c9544e277d4a3c90c26ab729d01c2fea8e49cdc59461a037d72029743463/OpenROAD-OpenDbPy-0.0.0.tar.gz",
"platform": "any",
"description": "# OpenDBPy\n\nThis repository contains only the OpenDB portion of the OpenRoad project. The code and build system has been slightly modified to support standalone building. Python setuptools has been added to allow the code to be converted into a wheel. \n\nYou can build and install the module by running:\n```\npython3 -m pip install . -v\n```\n\n# OpenDB\n\nOpenDB is a design database to support tools for physical chip design. It\nwas originally developed by Athena Design Systems. Nefelus, Inc. acquired\nthe rights to the code and open-sourced it with BSD-3 license in 2019 to support the DARPA\nOpenROAD project.\n\nThe structure of OpenDB is based on the text file formats LEF\n(library) and DEF (design) formats version 5.6. OpenDB supports a\nbinary file format to save and load the design much faster than using\nLEF and DEF.\n\nOpenDB is written in C++ 98 with standard library style iterators.\nThe classes are designed to be fast enough to base an application on without\nhaving to copy them into application-specific structures.\n\n\n## Directory structure\n\n```\ninclude/odb/db.h - public header for all database classes\nsrc/db - private/internal database representations\nsrc/lefin - LEF reader\nsrc/lefout - LEF writer\nsrc/defin - DEF reader\nsrc/defout - DEF writer\n```\n\n## Database API\n\nWe are still working on documenting the APIs. We have over 1,800 objects\nand functions that we are still documenting (for both TCL and Python).\n**Contributions are very welcome in this effort**. Find starting points below.\n\n### TCL\n\nAfter building successfully, run OpenDB Tcl shell using\n`../../build/src/odb/src/swig/tcl/odbtcl`. An example usage:\n\n```\nset db [dbDatabase_create]\nset lef_parser [new_lefin $db true]\nset tech [lefin_createTech $lef_parser ./src/odb/test/data/gscl45nm.lef]\n```\n\nYou can find examples on using the API from Tcl under `test/tcl/` directory.\n\nThe full set of the Tcl commands exposed can be found under\n`./build/src/swig/tcl/opendb_wrapper.cpp`. Search for `SWIG_prefix`.\n\n\n### Python\n\nAfter building successfully, run `openroad -python` to enable the Python\ninterpreter. You can find examples on using the API from Python under\n`test/python/` directory.\n\nTo list the full set of the Python classes exposed run `openroad -python`\nthen:\n```\nimport openroad\nimport odb\nprint(', '.join(dir(openroad)))\nprint(', '.join(dir(odb)))\n```\n\n### C++\n\nAll public database classes are defined in `db.h`. These class definitions\nprovide all functions for examining and modifying the database objects. The\ndatabase is an object itself, so multiple database objects can exist\nsimultaneously (no global state).\n\n`dbTypes.h` defines types returned by database class member functions.\n\nAll database objects are in the `odb` namespace.\n\n- `dbChip`\n- `dbBlock`\n- `dbTech`\n- `dbLib`\n\nAll database objects have a 32bit object identifier accessed with the\n`dbObject::getOID` base class member function that returns a `uint`. This\nidentifier is preserved across save/restores of the database so it should\nbe used to reference database object by data structures instead of pointers\nif the reference lifetime is across database save/restores. OIDs allow the\ndatabase to have exactly the same layout across save/restores.\n\nThe database distance units are **nanometers** and use the type `uint`.\n\n## Example scripts\n\n## Regression tests\n\nThere are a set of regression tests in /test.\n\n```\n./test/regression-tcl.sh\n./test/regression-py.sh\n```\n\n## Database Internals\n\nThe internal description included here is paraphrased from Lukas van Ginneken\nby James Cherry.\n\nThe database separates the implementation from the interface, and as a result,\neach class becomes two classes, a public one and a private one. For instance,\n`dbInst` has the public API functions, while class `_dbInst` has the private\ndata fields.\n\nThe objects are allocated in dynamically resizable tables, the implementation\nof which is in `dbTable.hpp`. Each table consists of a number of pages,\neach containing 128 objects. The table contains the body of the `struct`,\nnot a set of pointers. This eliminates most of the pointer overhead while\niteration is accomplished by stepping through the table. Thus, grouping these\nobjects does not require a doubly-linked list and saves 16 bytes per object\n(at the cost of some table overhead). Each object has an id, which is the\nindex into the table. The lowest 7 bits are the index in the page, while\nthe higher bits are the page number. Object id's are persistent when saving\nand reading the data model to disk, even as pointer addresses may change.\n\nEverything in the data model can be stored on disk and restored from disk\nexactly the way it was. An extensive set of equality tests and diff functions\nmake it possible to check for even the smallest deviation. The capability\nto save an exact copy of the state of the system makes it possible to create\na checkpoint. This is a necessary capability for debugging complex systems.\n\nThe code follows the definition of LEF and DEF closely and reflects many of\nthe idiosyncrasies of LEF and DEF. The code defines many types of objects\nto reflect LEF and DEF constructs although it sometimes uses different\nterminology, for instance, the object to represent a library cell is called\n`dbMaster` while the LEF keyword is MACRO.\n\nThe data model supports the EEQ and LEQ keywords (i.e., electrically equivalent\nand logically equivalent Masters), which could be useful for sizing. However,\nit does not support any logic function representation. In general, there is\nvery limited support for synthesis-specific information: no way to represent\nbusses, no way to represent logic function, very limited understanding of\nsignal flow, limited support of timing information, and no support for high\nlevel synthesis or test insertion.\n\nThe db represents routing as in DEF, representing a trace from point to point\nwith a given width. The layout for a net is stored in a class named `dbWire`\nand it requires a special `dbWireDecoder` (which works like an iterator)\nto unpack the data and another `dbWireEncoder` to pack it. The data model\ndoes not support a region query and objects that are in the same layer are\nscattered about the data model and are of different classes.\n\nThis means that whatever tool is using the layout information will have to\nbuild its own data structures that are suitable to the layout operations\nof that tool. For instance, the router, the extractor, and the DRC engine\nwould each have to build their unique data structures. This encourages\nbatch mode operation (route the whole chip, extract the whole chip, run\nDRC on the whole chip).\n\n## Limitations\n\n## FAQs\n\nCheck out\n[GitHub discussion](https://github.com/The-OpenROAD-Project/OpenROAD/discussions/categories/q-a?discussions_q=category%3AQ%26A+fastroute+in%3Atitle)\nabout this tool.\n\n\n## LICENSE\n\nBSD 3-Clause License. See [LICENSE](LICENSE) file.",
"bugtrack_url": null,
"license": "MIT",
"summary": "OpenDb fromo OpenROAD project",
"version": "0.0.0",
"split_keywords": [
"setuptools",
"extension",
"cpp",
"cmake",
"build",
"package",
"pypi",
"bindings",
"swig",
"pybind11"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3542c9544e277d4a3c90c26ab729d01c2fea8e49cdc59461a037d72029743463",
"md5": "f01c2b5f8977128663272319552f2286",
"sha256": "8e87738349ac357a7a90747984e861d79f9220d0e05ef20b1ae1245b62715927"
},
"downloads": -1,
"filename": "OpenROAD-OpenDbPy-0.0.0.tar.gz",
"has_sig": false,
"md5_digest": "f01c2b5f8977128663272319552f2286",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5220802,
"upload_time": "2023-03-18T15:14:46",
"upload_time_iso_8601": "2023-03-18T15:14:46.307470Z",
"url": "https://files.pythonhosted.org/packages/35/42/c9544e277d4a3c90c26ab729d01c2fea8e49cdc59461a037d72029743463/OpenROAD-OpenDbPy-0.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-18 15:14:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "jonpry",
"github_project": "OpenDb",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "openroad-opendbpy"
}
JSON
