Initial commit of public repository open_pdks.
diff --git a/README b/README
new file mode 100644
index 0000000..24fc238
--- /dev/null
+++ b/README
@@ -0,0 +1,574 @@
+open_pdks : A system for installing silicon foundry PDKs for open-source EDA tools
+(also maybe works for installing commercial tools)
+
+----------------------------------------------------------------------------------
+
+Written by Tim Edwards 2019 / 2020 for efabless (efabless.com)
+and Open Circuit Design (opencircuitdesign.com)
+
+----------------------------------------------------------------------------------
+
+Introduction:
+
+ Silicon foundry PDKs are notoriously non-standard, and files obtained
+ from the foundry may end up in any possibly configuration of files and
+ folders. In addition, silicon foundries are notorious among open source
+ EDA tool enthusiasts for supplying user setups for commercial EDA tools
+ and all but ignoring open source EDA tools. Open_pdks aims to mitigate
+ the problem by defining a standard layout of files and directories for
+ known open standard formats (e.g., SPICE, verilog, liberty, LEF, etc.)
+ and for various open source EDA tools (e.g., magic, netgen, OpenROAD,
+ klayout) using a Makefile system and a number of conversion scripts to
+ ensure that for any process, all files needed by all EDA tools can be
+ found in predictable locations.
+
+ The scripts aim to be as general-purpose as possible to allow easy
+ adaptation to new tools, formats, and foundries. Where foundry data
+ is intractably unusable, custom install files can be added to overwrite
+ or annotate vendor data as needed.
+
+ Each foundry process is a subdirectory of the open_pdks top level and
+ has its own Makefile. The typical install process is to cd to the
+ foundry top level and run "make" (see below for details).
+
+ The general file structure created by open_pdks is as follows:
+
+ <foundry_root>/
+ <name_of_pdk_variant_1>/
+ <name_of_pdk_variant_2>/
+ ...
+ <name_of_pdk_variant_x>/
+ libs.tech/
+ <name_of_EDA_tool_1>/
+ <name_of_EDA_tool_2>/
+ ...
+ <name_of_EDA_tool_x>/
+ <EDA_tool_setup_files>
+ libs.ref
+ <name_of_IP_library_1>/
+ <name_of_IP_library_2>/
+ ...
+ <name_of_IP_library_x>/
+ <name_of_file_format_1>
+ <name_of_file_format_2>
+ ...
+ <name_of_file_format_x>
+ <vendor_files>
+
+ Note that this format is very general and does not constrain the
+ EDA tools supported or file formats supported, so long as there
+ are scripts in the system to provide that support. It is intended
+ that open_pdks can be extended as needed to support new tools or
+ new file formats.
+
+ Current EDA tools supported in this version of open_pdks:
+ Tool Directory name
+ --------------------------
+ ngspice ngspice
+ magic magic
+ netgen netgen
+ klayout klayout
+ qflow qflow
+ openlane openlane
+
+ Current IP library file formats supported in this version of open_pdks*:
+ Format Directory name
+ --------------------------
+ CDL cdl
+ SPICE spice
+ magic mag, maglef
+ LEF lef, techlef
+ GDS gds
+ verilog verilog
+ liberty lib
+ PDF** doc
+
+ (* "Supported" meaning expected/handled by conversion scripts;
+ as noted, the install is very general purpose and any name
+ can be used as a target for any vendor or custom files.)
+ (** or HTML or any valid document format, plus supporting files.)
+
+How to use open_pdks:
+
+ There are a seriously limited number of open foundry PDKs. Those that
+ are known (SkyWater, MOSIS SCMOS) are included in the repository. In
+ other cases (X-Fab XH035, XH018) it is possible to get an extension to
+ open_pdks from a known trusted source through NDA verification with
+ the foundry. In all other cases, foundries should be berated until
+ they agree to support the open_pdks format.
+
+ Open_pdks does not attempt to keep any foundry data to the extent
+ possible. Instead, it adapts to the file structure available from
+ whatever system each foundry uses for downloads. Each foundry
+ directory should contain a README file that details how to obtain
+ downloads from the foundry, and what files need to be downloaded.
+ Since the download methods vary wildly, it is up to the user to obtain
+ the foundry data as instructed. The Makefile in the open_pdks foundry
+ directory then needs to be edited to set the correct path to the
+ foundry source data.
+
+ The installation is a bootstrapping process, so needs to be done in
+ stages. The first stage installs setup files for all the EDA tools.
+ The second stage installs IP libraries (e.g., standard cells, padframe
+ I/O, analog circuits) and depends heavily on the use of the open EDA
+ tools themselves to fill in any missing file formats. Therefore the
+ tool setup files need to be installed first, and then the IP libraries.
+ If using a distributed install (see below), then the tool setup files
+ need to be installed and distributed (relocated to the final run-time
+ location) before the IP libraries are installed.
+
+ There are two distinct install types supported by open_pdks:
+
+ (1) Local install: Use a local install when the EDA tools will be run
+ on a single host, and all the PDK data are on the same host.
+
+ The local install sequence is:
+
+ make Generate local staging area
+ make install-local Migrate to install directory
+
+ (2) Distributed install: Use the distributed install when the PDK
+ will be run from multiple hosts, but will be installed into a
+ different location such as a git repo which is then distributed to
+ all hosts, and may not itself reside in the same root directory tree.
+
+ The distributed install sequence is:
+
+ make Generate local staging area
+ make install-dist Migrate to distribution directory
+
+ Note that local installs may opt to make symbolic links back to the
+ foundry sources, where possible (see options for foundry_install.py,
+ below). Distributed installs and local installs may also make
+ symbolic links from any PDK variant back to a "master" PDK variant,
+ where possible (that is, where the files are the same). For example,
+ a standard cell library will probably be compatible with all metal
+ back-end stacks, and so only one copy of all the library files is
+ needed in one of the PDK variants. For the other PDK variants, the
+ same files are all symbolic links to the files in the first PDK
+ variant. But an I/O library would have different layouts for different
+ metal back-end stacks, so layout-dependent files like GDS would be
+ different for each PDK, but layout-independent files like verilog
+ might be symbolic links to files in the first PDK.
+
+Prerequisites:
+
+ The following tools/software stacks are needed to run open_pdks:
+
+ python3
+
+ magic opencircuitdesign.com/magic or github.com/RTimothyEdwards
+
+ assumed to be installed and discoverable in the standard
+ search path as defined by the shell (version 8.2+ required)
+
+How to make or update an open PDK:
+
+ The backbone of the open_pdks system is a set of scripts found in the
+ common/ subdirectory. The two main scripts are "preproc.py" and
+ "foundry_install.py", with a host of supporting scripts.
+
+ Creating a new PDK starts with generating a Makefile, which can be
+ done by copying a Makefile from an existing project. The first thing
+ to do is to define the number of PDK variants (usually based on back-end
+ metal stacks available, but can also include front-end options, especially
+ if they are mutually exclusive rather than simply additional masks).
+ Then create the make and make-install targets for local and distributed
+ install, including install (plain), install-vendor, and install-custom.
+ Define the default source and target paths.
+
+ (Needed: A "make makefile" script that generates the "local" and "dist"
+ automatically, and potentially can also make all the different PDK
+ targets automatically, from a much shorter and simpler master Makefile.)
+
+ Create the basic scripts for tools. Since foundries do not support open
+ EDA tools, it is inevitable that these files need to be created by hand
+ unless there is an option to import other formats. Because Magic is used
+ heavily by open_pdks to create missing file formats from other existing
+ file formats, a Magic techfile is critical. Each of the basic scripts
+ will contain #ifdef ... #endif and similar conditionals to allow the
+ script to be parsed for each target PDK variant. Each of these scripts
+ is passed through common/preproc.py to handle the conditionals. Of course,
+ it is possible to make a separate file for each PDK variant as long as the
+ Makefile handles them properly, but use of the preproc.py script allows
+ all the PDK variants to be handled in the same way, simplifying the Makefile.
+
+ --------------------------------------------------------------------------
+ preproc.py Usage:
+
+ preproc.py input_file [output_file] [-D<variable> ...]
+
+ Where <variable> may be a keyword or a key=value pair
+
+ Syntax: Basically like cpp. However, this preprocessor handles
+ only a limited set of keywords, so it does not otherwise mangle
+ the file in the belief that it must be C code. Handling of boolean
+ relations is important, so these are thoroughly defined (see below)
+
+ #if defined(<variable>) [...]
+ #ifdef <variable>
+ #ifndef <variable>
+ #elseif <variable>
+ #else
+ #endif
+
+ #define <variable> [...]
+ #undef <variable>
+
+ #include <filename>
+
+ <variable> may be
+ <keyword>
+ <keyword>=<value>
+
+ <keyword> without '=' is effectively the same as <keyword>=1
+ Lack of a keyword is equivalent to <keyword>=0, in a conditional.
+
+ Boolean operators (in order of precedence):
+ ! NOT
+ && AND
+ || OR
+
+ Comments:
+ Most comments (C-like or Tcl-like) are output as-is. A
+ line beginning with "###" is treated as a preprocessor
+ comment and is not copied to the output.
+
+ Examples;
+ #if defined(X) || defined(Y)
+ #else
+ #if defined(Z)
+ #endif
+
+ --------------------------------------------------------------------------
+
+ The script common/foundry_install.py handles all the IP library processing
+ and installation. It generates the local directory structure and populates
+ the directories with foundry vendor data, and filters or otherwise uses
+ open EDA tools to generate missing standard file formats or create file
+ formats needed by the open EDA tools.
+
+ foundry_install.py Usage:
+
+ foundry_install.py [option [option_arguments]] ...
+
+ All options begin with "-" and may be followed by one or more
+ arguments (that do not begin with "-"). The foundry_install.py
+ script may be called multiple times, although it is best to
+ group together all files for the installation of an IP library,
+ since the options given will be used to determine what files are
+ missing and need to be generated.
+
+ Global options:
+ -link_from <type>
+ Make symbolic links to vendor files from target
+ Types are: "none", "source", or a PDK name.
+ Default "none" (copy all files from source)
+ -source <path>
+ Path to source data top level directory
+ -target <path>
+ Path to target top level directory
+ -local <path>
+ For distributed installs, this is the local
+ path to target top level directory.
+
+ -library <type> <name>
+ The install target is an IP library with
+ name <name>.
+ -ef_format
+ Use the original efabless format for file
+ installs. This has several differences from
+ then no-efabless install. The most important
+ is that the order of directories for IP libraries
+ is <file_format>/<library_name> instead of
+ <library_name>/<file_format>. As the efabless
+ platform migrates to the open_pdks developing
+ standard, this use should eventually be
+ deprecated. In open_pdks, the option is set
+ from the EF_FORMAT variable setting in the Makefile.
+
+ All other options represent installation into specific directories.
+ The primary rule is that if foundry_install.py is passed an option
+ "-library" (see syntax below), then all other non-global options
+ represent subdirectories of the IP library, given the same name as
+ the option word following the "-". If the foundry_install.py command
+ line does not have an option "-library", then all non-global options
+ represent per-EDA tool subdirectories, where the name of the subdirectory
+ is the same as the option word following the "-".
+
+ Each tool install option has the syntax:
+
+ -<tool_name> <path> [<option_arguments>]
+
+ Each IP library install option has the syntax:
+
+ -<file_format_name> <path> [<option_arguments>]
+
+ The <path> is a directory path that is relative to the path prefix
+ given by the -source option. The path may be wildcarded with the
+ escape string "%l", which is replaced by the name of the library,
+ and for simplicity with versioning, "%v" will be interpreted to
+ match any versioning string in the form "major[.minor[.rev]]".
+ Note that only the numerical part of a versioning string is
+ represented, so, for example, to match "/V1.1.0/" the <path> should
+ use "/V%v/". In the unlikely event of a percent character in the
+ path, use the escape string "%%".
+
+ "*" has the usual meaning of matching any characters in a name (see
+ python glob.glob() command for reference). However, for backwards
+ compatibility with earlier versions of open_pdks, the library name
+ in the path may also be wildcarded with "*" in the specific text
+ "/*/".
+
+ Library name wildcarding in either form is only valid if "-library"
+ is given as an an option.
+
+ (Note that the INSTALL variable in the Makefile starts with "set -f"
+ to suppress the OS from doing wildcard substitution; otherwise the
+ wildcards in the install options will get expanded by the OS before
+ being passed to the install script.)
+
+ Library option:
+
+ -library <type> <name> [<target>]
+
+ <type> may be one of the following:
+
+ digital Digital standard cells
+ primitive Primitive devices
+ general All others
+
+ Analog and I/O libraries fall under the category "general".
+
+ <name> is the vendor name of the library.
+
+ [<target>] is the (optional) local name of the library. If omitted,
+ then the vendor name is used for the target (there is no particular
+ reason to specify a different local name for a library).
+
+ Any number of libraries may be supported, and one "-library" option
+ may be provided for each supported library. The use of multiple
+ libraries for a single run of foundry_install.py only works if the
+ formats (gds, cdl, lef, etc.) happen to all work with the same wildcards.
+ But it is generally most common to declare only one library name per
+ call to foundry_install.py.
+
+ Common foundry_install.py options when used with "-library":
+
+ -techlef <path> [option_arguments] Technology LEF file
+ -doc <path> [option_arguments] library documentation
+ -lef <path> [option_arguments] LEF file
+ -spice <path> [option_arguments] SPICE netlists
+ -cdl <path> [option_arguments] CDL netlists
+ -lib <path> [option_arguments] Liberty timing files
+ -gds <path> [option_arguments] GDS layout data
+ -verilog <path> [option_arguments] Verilog models
+
+ Any name can be used after the "-" and the installation of files
+ will be made into a directory of that name, which will be created
+ if it does not exist. The names used above are preferred, for
+ the sake of compatibility between EDA tools.
+
+ Of special note is "techlef", as technology LEF files are often
+ associated with a PDK and not an IP library. In this system,
+ the technology LEF file should be associated with each standard
+ cell library for which it is intended.
+
+ [option_arguments] may be one of the following:
+
+ up <number>
+ Any tool option can use this argument to indicate that
+ the source hierarchy should be copied entirely, starting
+ from <number> levels above the files indicated by <path>.
+ For example, if liberty files are kept in multiple
+ directories according to voltage level, then
+
+ -liberty x/y/z/PVT_*/*.lib
+
+ would install all .lib files directly into
+ libs.ref/<libname>/liberty/*.lib while
+
+ -liberty x/y/z/PVT_*/*.lib up 1
+
+ would install all .lib files into
+ libs.ref/liberty/<libname>/PVT_*/*.lib.
+
+ nospec
+ Remove timing specification before installing (used with
+ verilog files only; could be extended to liberty files).
+
+ compile
+ Create a single library from all components. Used when a
+ foundry library has inconveniently split an IP library
+ (LEF, CDL, verilog, etc.) into individual files.
+
+ compile-only
+ Same as argument "compile", except that the individual
+ files are not copied to the target; only the compiled
+ library is created.
+
+ stub
+ Remove contents of subcircuits from CDL and SPICE netlist,
+ or verilog files. This is useful to LVS and other tools
+ to know the order of pins in a circuit (for CDL or SPICE),
+ or simply to ignore the contents of the file (any format)
+ so that the circuit in question is treated as a "black box".
+
+ priv
+ Mark the contents being installed as privleged, and put
+ them in a separate root directory libs.priv where they
+ can be given additional read/write restrictions.
+
+ rename <file_name>
+ Rename the file being copied to the name of the argument.
+ This can be used to copy one file into multiple destination
+ libraries and give each copy a name related to the
+ destination library.
+
+ filter <script_file_path>
+ Process all files through the script <script_file_path>,
+ which is given as a relative path to the directory
+ containing the Makefile. The filter script traditionally
+ is put in local subdirectory custom/scripts/. The filter
+ script should be written to take a single argument, which
+ is the path to a file, and process that file, and overwrite
+ the file with the result. Commonly used filters are found
+ in the common/ directory. See common/fixspice.py for an
+ example.
+
+ noclobber
+ Mainly diagnostic. When specified, any temporary files
+ used during installation will be retained instead of
+ deleted after use. This includes, for example, scripts
+ passed to magic for running extraction or file format
+ generation. It is useful when debugging problems with
+ the install.
+
+ anno
+ Currently only supported for LEF files. This argument
+ indicates that the vendor LEF files should be used only
+ for annotating GDS input with port location information,
+ but the LEF files themselves should not be installed.
+
+ File conversions handled by foundry_install.py:
+
+ The following file format conversions can be done automatically by
+ foundry_install.py:
+
+ CDL to SPICE: A CDL netlist or library can be converted to a
+ general-purpose SPICE netlist that can be read
+ by any tool that can read Berkeley SPICE 3f5
+ syntax.
+
+ GDS to LEF: An abstract view can be generated from a full
+ layout view using Magic.
+
+ GDS to SPICE: In the absence of any netlist, Magic will
+ extract a SPICE netlist from a full layout.
+
+ SPICE (any) to SPICE (ngspice): The fixspice.py script will
+ attempt to convert any SPICE model file,
+ cell library, or netlist to a form that is
+ compatible with ngspice version 30.
+
+ open_pdks additional Makefile notes:
+
+ The "make install-local" ("make install-dist") step is generally
+ broken into individual make sections, one for each tool (e.g.,
+ magic, netgen, klayout). There is an additional section called
+ "general" which installs a ".config" directory at the PDK top
+ level, containing a file "nodeinfo.json" which has general
+ information about the PDK that may be used by any tool that
+ understands the key:value pairs used in the JSON file. Keys used
+ are as follows:
+
+ foundry : Short name of the foundry, equal to the foundry
+ directory root, above the PDK variants.
+ foundry-name : Long name of the foundry.
+ node : The name of the PDK variant
+ feature-size : The foundry process feature size (e.g., 130nm)
+ status : "active" or "inactive". May be used by tools
+ to present or hide specific PDK variants.
+ description : Long text description of the process variant
+ (e.g., 6-metal stack + MiM caps)
+ options : List of options, corresponding to the definitions
+ used in the Makefile and passed to preproc.py.
+ stdcells : List of standard cell libraries available for this
+ PDK variant.
+ iocells : List of I/O pad cell libraries available for this
+ PDK variant.
+
+ Note that the JSON file is, like other EDA tool setup files, usually a
+ master file that is parsed by preproc.py; therefore when specifying
+ "options", use #undef before specifying each option name so that the
+ option name itself is ignored by the pre-processor.
+
+
+Goals of the open_pdks project:
+
+ The intended goal of open_pdks is to be able to support as many open source
+ EDA tools as practical, and to be able to generate all needed files for
+ those tools from any sufficiently complete set of vendor files.
+
+ A number of file converions are not available but would be useful to have:
+
+ SPICE to liberty: Create timing files by running simulations
+ on SPICE netlists using ngspice.
+
+ liberty to verilog: Use the function statements in liberty
+ format to create verilog primitives. Maybe
+ use liberty timing information to generate
+ LEF specify sections.
+
+ verilog to liberty: Reverse of the above. Use verilog logic
+ tables and specify sections to generate liberty
+ functions and timing tables.
+
+ File formats that need to be supported:
+
+ Schematic and symbol: There are few standards, so either everyone
+ needs to agree on a good format to use, or there
+ needs to be a lot of scripts to do conversions
+ between formats. Open EDA tools that could be
+ supported include:
+
+ electric, xcircuit, kicad, sue2
+
+ Other open source EDA tools that need to be supported:
+
+ OpenROAD
+ Coriolis2
+ (add more here. . .)
+
+ Commercial EDA tools can potentially be supported under this same system,
+ provided sufficient compatibility with the file system structure.
+
+ Other scripts needed:
+
+ Project setup script: It would be useful to define a "standard
+ project file structure" that is similar to the standard PDK file
+ structure defined in open_pdks. The preferred project setup
+ based on the efabless model is:
+
+ <project_name>
+ .config/
+ techdir (symbolic link to open_pdks PDK)
+ project.json (information file for tools)
+ <tool_name> (magic, qflow, ngspice, etc.) or
+ <format_name> (spice, gds, verilog, etc.)
+
+ In general, <tool_name> directories are intended to be workspaces
+ for specific EDA tools (and may have their own nested hierarchies;
+ e.g., qflow/<digital_block>/source,synthesis,layout) while
+ <format_name> is a place to keep (final) files of a specific format,
+ with the intention that any project can easily be made into an
+ IP library and folded into the open_pdks scheme with little effort.
+
+ The project.json file contains project information that can be used
+ by a script to build a setup for any EDA tool. One goal of the
+ project.json file is to define "datasheet" (documented elsewhere)
+ that can be used to drive characterization simulations and create
+ a datasheet for the project. Field "ip-name" of "datasheet" is
+ the canonical name of the project, which can be distinguished from
+ the project directory top-level name, such that the project can be
+ moved or copied without affecting the tool flows.
