1  # Description
  2  
  3  PDK Master is a tool to manage [PDK](https://en.wikipedia.org/wiki/Process_design_kit)s for ASIC design and a framework for designing circuits and layouts in those technologies.
  4  It is a Python framework under heavy development and with an unstable API.
  5  
  6  # Release history
  7  
  8  * [v0.11.0](https://gitlab.com/Chips4Makers/PDKMaster/-/commits/v0.11.0): split off
  9    pdkmaster.io.klayout module
 10  * [v0.10.2](https://gitlab.com/Chips4Makers/PDKMaster/-/commits/v0.10.2): includes support for
 11    IHP SG13G2 IO cells in [c4m-pdk-ihpsg13g2](https://gitlab.com/Chips4Makers/c4m-pdk-ihpsg13g2)
 12  * v0.10.1: Smaller layout and DRC improvements guided by work on the IHP
 13    sg13g2 IO cells. Please refer to individual git commit for the details.
 14  * v0.10.0: Start newer minor version by merging API breaking changes.
 15    I will backwards compatibility for code using deprecated *T types and for Resistor and Diode
 16    primitive creation that explicitly specify None for implant or min_implant_enclosure property.
 17    Technology.substrate() property has been removed and wafer_.outside() function.  
 18    For the rest no code difference with v0.9.6.  
 19    Originally it was planned to have v1.0 to be released after the v0.9.x releases. For the
 20    layout code in PDKMaster still major reworks and API breakage is expected and v1.0 is delayed
 21    until this has stabilized more.
 22  * v0.9.6: Release of several changes used in improved version of c4m-flexcell and c4m-flexio
 23    Mostly small changes or bug fixes. One bigger change is that now more than one implant layer
 24    can be drawn around a WaferWire interconnect. Resistor and Diode primitives now allow to
 25    define them with multiple implant layers and generate the layout for these multiple implant
 26    layers.
 27    After this release some API breaking changes will be merged.
 28  * v0.9.5: allow use of MOSFET.gate4mosfet attribute before MOSFET is added to Technology.
 29    This allows having rules added to the technology that are using the gate of a specific
 30    MOSFET.
 31  * v0.9.4:
 32    * Support for WaferWire without an implant for diode, MOSFET etc.
 33    * Roadworks on layer manipulation
 34    * API improvements, unification and deprecation
 35  * v0.9.3:
 36    * First LEF/DEF support: support exporting tech.lef file
 37    * Bug fixing
 38  * v0.9.2: support new namespace in coriolis export
 39  * v0.9.1: fix coriolis export, primitive type values are not python types.
 40  * v0.9.0: [release notes](https://gitlab.com/Chips4Makers/PDKMaster/-/blob/v0.9.0/ReleaseNotes/v0.9.0.md)
 41  * v0.3.0: [release notes](https://gitlab.com/Chips4Makers/PDKMaster/-/blob/v0.3.0/ReleaseNotes/v0.3.0.md)
 42  * v0.2.1: add klayout dependency
 43  * v0.2.0: [release notes](https://gitlab.com/Chips4Makers/PDKMaster/-/blob/v0.2.0/ReleaseNotes/v0.2.0.md)
 44  * v0.1: [release notes](https://gitlab.com/Chips4Makers/PDKMaster/-/blob/v0.2.0/ReleaseNotes/v0.1.md)
 45  
 46  # Overview
 47  
 48  Currently no documentation is available, the documentation is planned to be added as part of the stabilization of the PDKMaster API. To show the things PDKMaster wants to solve here an overview of the different parts of the current PDKMaster code base:
 49  
 50  * __pdkmaster__: the top python module
 51    * __`_util.py`__: some helper functions and classes
 52    * __technology__:
 53    this submodule handles the description of an ASIC technology with final target to allow describe that in one python file.
 54      * __`property_.py`__: base class to represent properties on operations that can be done on them.
 55      * __`rule.py`__: abstract base class to represent a rule object, e.g. a condition on properties that has to be fulfilled to be manufacturable.
 56      * __`mask.py`__: class to represent the photolithography masks used in ASIC production and the properties on them. The latter are then used to define design rules.
 57      * __`edge.py`__: class representing mask edges and it's properties to be used in design rules.
 58      * __`wafer.py`__: object to represent a (silicon) wafer that is the start of processing and that is auto-connected to some device ports.
 59      * __`net.py`__: class representing a net, e.g. o group of conductors in a circuit that are connected together.
 60      * __`primitive.py`__: classes for all possible device primitives available in a technology. This goes from low-level interconnect to transistors. As indication of the content here the exported classes are given:
 61        ```python
 62        __all__ = ["Marker", "Auxiliary", "ExtraProcess",
 63                   "Implant", "Well",
 64                   "Insulator", "WaferWire", "GateWire", "MetalWire", "TopMetalWire",
 65                   "Via", "PadOpening",
 66                   "Resistor", "Diode",
 67                   "MOSFETGate", "MOSFET", "Bipolar",
 68                   "Spacing",
 69                   "UnusedPrimitiveError", "UnconnectedPrimitiveError"]
 70        ```
 71        The object attibutes defined by these classes are used to derive mask design rules.
 72  
 73      * __`technology_.py`__: class to define the capability of a certain technology: all support devices, the masks needed to define them and the rules for making circuit in this technology.
 74    * __dispatch__: helper classes inspired by the [Visitor design pattern](https://en.wikipedia.org/wiki/Visitor_pattern).
 75    * __design__: support code for making circuits compliant with a given technology.
 76      * __`circuit.py`__: defines a factory that allows to generate objects of the Circuit class using devices from a given technology.
 77      * __`layout.py`__: classes to define layout compliant with a given technology and a factory to generate layouts for a given circuit that are technology design rule compliant.
 78      * __`library.py`__: contains:
 79        * __Cell class__: representing several possible circuit representations and layouts of a block with the same function
 80        * __Library class__: represent a collections of cells
 81    * __io__: submodule to import and export technology data, circuit and layouts. It also allows
 82      to interface with external tools.
 83      * __parsing__: submodule to parse setup files for other EDA tools and extract data to build a PDKMaster technology object based on this data.
 84        * __`skill_grammar.py`__: modgrammar based parser for [SKILL](https://en.wikipedia.org/wiki/Cadence_SKILL)(-like) files. [SKILL](https://en.wikipedia.org/wiki/Cadence_SKILL) is the Cadence bastardized version of [Lisp](https://en.wikipedia.org/wiki/Lisp_(programming_language)).
 85        * __`tf.py`, `display.py`, `layermap.py`, `assura.py`__: classes for representing Cadence EDA files based on the [SKILL](https://en.wikipedia.org/wiki/Cadence_SKILL) grammar.
 86      * __pdkmaster__: support code to export a PDKMaster technology as Python souce code; main targeted use case to use the parsing submodule to extract data from NDA covered PDK and generate PDKMaster Technology object without needing to disctribute NDA covered data.
 87      * __coriolis__: support code to generate Coriolis technology setup, cells and libraries from PDKMaster objects.
 88      * __klayout__: support code to generate klayout Technology setup for PDKMaster Technology object including DRC and LVS scripts.
 89      * __spice__: support code to convert PDKMaster Circuit to use in SPICE simulations;
 90      currently PySpice is used to interface with SPICE.
 91  
 92  The current code base has been gradually grown to allow to do a 0.18µm prototype layout of the NLNet sponsored Libre-SOC project. It has known (and unknown) inconsistencies and shortcomings. A full revision of the current API is planned without any backwards guarantees whatsoever. As this is an open source project it is meant to be used by other people but one should be aware that user code using PDKMaster has a high chance of breaking with each commit done to the repository in the near future.
 93  
 94  # Installation
 95  
 96  All dependencies for installation should be available so PDKMaster should be able to installed by a simple pip command.
 97  
 98  ```console
 99  % pip install PDKMaster
100  ```
101  
102  To install build dependencies:
103  ```console
104  % pip install -r dev-requirements.txt
105  ```
106  
107  More in depth discussion of different `pip` use case scenarios is out of the scope of this document.
108  
109  Run time dependencies:
110  
111  - [modgrammar](https://pythonhosted.org/modgrammar/)
112  - [shapely](https://shapely.readthedocs.io/en/latest/manual.html), [descartes](https://pypi.org/project/descartes/) (deprecated way of plotting in notebooks)
113  - [PySpice](https://pyspice.fabrice-salvaire.fr/pages/documentation.html) >= 1.5
114  - klayout ([pypi](https://pypi.org/project/klayout/), [home](https://www.klayout.de/)): for pdkmaster.io.klayout
115  
116  # Licensing Rationale
117  
118  Open source projects and it's surrounding community can only strive when improvements to the
119  code or application of the code itself are released to the public and allowed to be used by
120  them. Copyleft type license are using the licensing terms to guarantee this actually happens
121  and no party uses a 'take-but-don't-give-back' approach. The
122  [GNU Aferro General Public License V3.0](LICENSES/agpl-3.0.txt) is used as main license for
123  the code in this project as it is a copyleft type license that is also applicable to cloud
124  services without binary distribution of the code.
125  
126  One of the problems with a strict copyleft license is that it can introduce incompatibilities
127  with code released under other open source licenses. In order to improve compatibility and
128  thus also reusablity the code in this repo is multi-licensed. Multi-licensing under
129  established open source licenses was preferred over custom extension of licenses.
130  
131  The [GNU General Public License V2.0](LICENSES/gpl-2.0.txt) was added as optional license in
132  order to allow derived code not to be bound by the anti-[tivoization](
133    https://en.wikipedia.org/wiki/Tivoization
134  ) clauses introduced in the [GNU General Public License Version 3](
135    https://www.gnu.org/licenses/gpl-3.0-standalone.html
136  ). The latter was not deemed necessary for this project and the addition was done to increase
137  compatibility with some corporate policies.
138  
139  The [CERN Open Hardware Licence Version 2 - Strongly Reciprocal](LICENSES/cern_ohl_s_v2.txt) is included as it is a copyleft license specifically targeted for hardware but incompatible
140  with the GPL licenses.
141  
142  The [Apache License Version 2.0](LICENSES/apache-2.0.txt) is included to maximize compatiblity
143  with existing open source code. One is supposed to not use it to avoid having to release one's
144  own derived code to the public. If you plan development of a project in a proprietary way, one
145  is kindly asked to not derive one's code from this project's code.
146  
147  In future the list of allowed licenses may be reduced. A reason could be that such an action
148  is deemed necessary by the project maintainers to encourage open sourcing of derived code.
149  
150  Analog to how the object files and the executables generated by the gcc compiler are not
151  necessarily goverened by the GPL license, the multi-licensing applies only to code derived
152  from code in this repository. Output files generated through the use of the code in this
153  repository are not by default bound to the multi-licensing requirements of this project's
154  code.
155  
156  # Copyright
157  
158  The code in this repo is copyrighted by all the contributors to it; git is
159  used to track this copyright.