------------------------------------
open_pdks
----------------------------------------
Master PDK generator for SkyWater Sky130
Hybrid 180nm / 130nm foundry process
for open source EDA tools
----------------------------------------

-------------------------------------------------------------------------------
Quick summary (TL;DR):

    Prerequisites:

    	sudo apt-get install python3

    The Magic VLSI layout tool is used often by the installation.  If you do
    not have it, then obtain it and install with the following:

    	sudo apt-get install m4 tcsh tcl-dev tk-dev

	git clone https://github.com/RTimothyEdwards/magic
	cd magic
	./configure
	make
	sudo make install

    Open_PDKs SKY130 Installation: Most people will want to run the following
    for PDK installation:

	./configure --enable-sky130-pdk
	make
	sudo make install

    This will download and install the SkyWater SKY130 PDK, the SKY130 setup
    files for xschem, and a third-party library containing alphanumeric layouts.
    If you prefer an installation in your user space, then use configure option
    "--with-sky130-local-path=<path>" with <path> being some alternative like
    ~/pdks, and "make install" does not need to be run sudo.

    With he above configuration line, the PDK files will be installed into
    the path
		/usr/share/pdks/sky130A/

    From open_pdks version 1.0.269, there is a process variant

		/usr/share/pdks/sky130B/

    which reflects support for ReRAM.

-------------------------------------------------------------------------------
Detailed instructions for the patient reader:
-------------------------------------------------------------------------------
Prerequisites:

1. EDA tools:

    For installing files to use with the Magic layout tool, Magic must be installed.
    Obtain Magic from:

	https://github.com/RTimothyEdwards/magic

    No other tools are required for installation, although open_pdks will
    generate and install the setup files for a number of tools.

2. Foundry source files [optional]:

    If you do not have the foundry source files, the latest version will
    be downloaded from github, built, and installed locally in the
    open_pdks/sources/ directory.  If you have the foundry source files,
    then you can pass the location to the open_pdks configure script.  In
    that case, the sources will need to be completely built.  The
    instructions below are needed ONLY if you intend to download and
    install the PDK sources outside of open_pdks.  Instructions below
    are only valid for the SkyWater SKY130 process.  If additional
    open-source PDKs become available, instructions will be added as
    needed.

    Obtain sources for the SkyWater sky130 130nm process from the git repository
    at the following location:

	 https://github.com/google/skywater-pdk

    This repository may go in any convenient location.  The Makefile suggests
    the target location ~/projects/foundry/skywater-pdk but any location will
    do as long as the --enable-sky130-pdk= configuration option value is set
    appropriately.

    So cd to the target location parent directory (e.g., "cd ~/projects/foundry")
    and run the following command:

	 git clone https://github.com/google/skywater-pdk

    Note that many of the files in the PDK are too large for a single git
    repository, and so each IP library in the PDK has been placed in a
    submodule.  There are multiple versions of each library, and it is
    nearly certain that you will only want to deal with the "latest" version
    of each.  To make sure you have the submodules for the latest version of
    each supported IP library, do:

	cd skywater-pdk
	git submodule init libraries/sky130_fd_io/latest
	git submodule init libraries/sky130_fd_pr/latest
	git submodule init libraries/sky130_fd_sc_hd/latest
	git submodule init libraries/sky130_fd_sc_hvl/latest
	[git submodule init libraries/sky130_fd_pr_reram/latest]
	[git submodule init libraries/sky130_fd_sc_hdll/latest]
	[git submodule init libraries/sky130_fd_sc_hs/latest]
	[git submodule init libraries/sky130_fd_sc_ms/latest]
	[git submodule init libraries/sky130_fd_sc_ls/latest]
	[git submodule init libraries/sky130_fd_sc_lp/latest]
	git submodule update

    The liberty (.lib) files are the largest of all and so individual files
    are too large for the git repo and need to be assembled by script.  To
    do that, do:

	make timing

    That installs all of the Google/Skywater files.  To keep the overhead low,
    you may initialize only the submodules that you need.  At a minimum, the
    I/O library, primitive devices, and the high density and high voltage
    digital standard cell libraries should be installed.  The remaining standard
    cell libraries are optional, as needed for low-leakage, high speed, low power,
    etc., applications.

    Then follow the instructions below for generating the additional files
    for supporting the open source EDA tool flows.

PDK Installation:

    There are two methods for installation:  Local and Distribution.  Use Local
    installation if you are installing on a single host computer.  Use Distribution
    installation if you are installing into a respository (such as git) that will
    be distributed to multiple hosts.

Step 1:

    Run "configure" to set the paths to the Google/SkyWater source
    repository and to set the path to the install location.  Note that
    the configure script is located in the open_pdks top level directory,
    not in the foundry subdirctory, and must be run from the top level
    directory.  The mandatory configure options are as follows:

	--enable-sky130-pdk[=/path/to/sky130/pdk/source]
		This is mandatory for specifying that the installation
		is for the SKY130 PDK.  If the path is specified, then
		the PDK is assumed to already be downloaded and installed.
		If not, then the PDK will be downloaded automatically
		from github and installed.  Note that the PDK repository
		is very large, contains submodules, and the submodules
		need to compile the liberty timing files, which can
		take a very long time.  Be patient.

	--with-ef-style
		Select this for an efabless-style file structure.
		The default is "no".  There are some differences in
		these two styles, the most important of which being
		that the order of directories for the IP libraries
		is <file_format>/<library_name> instead of
		<library_name>/<file_format>. Other differences
		include version tracking of the Magic setup files
		and the location of the technology LEF file.

	--with-sky130-variants=all|A|B
		When set to "all" (which is the default), both variants
		sky130A and sky130B are generated and installed.   If
		only one PDK variant needs to be installed, then use
		this option to restrict the installation to a single
		PDK variant.

	--with-sky130-link-targets=none|source
		"none" copies files from the source directories to
		the target.  "source" makes symbolic links to the source
		directories.  Use "source" only if doing a local install,
		and the source foundry data will not be deleted.  For
		distribution installations, the value must be set to
		"none".

	--enable-alpha-sky130[=<path>] 
		The path to the sky130_ml_xx_hd library, a third-party
		library containing layouts of alphanumeric characters
		for adding text to layout.  If the configuration option
		or the path is not specified, then the library will be
		downloaded from github automatically.  To disable this
		package, use "--disable-alpha-sky130".

	--enable-xschem-sky130[=<path>]
		The path to the SKY130 setup for the xschem schematic
		entry/schematic capture tool.  If the configuration
		option or the path is not specified, then the library
		will be downloaded from github automatically.  To disable
		this package, use "--disable-xschem-sky130".

	--enable-sram-sky130[=<path>]
		This 3rd party library contains pre-compiled and verified
		memory blocks from the OpenRAM open source memory compiler.
		It is disabled by default due to the length of time
		required to install, but it is recommended if you will be
		using SRAM in a design.

	--enable-osu-t12-sky130[=<path>]
		This 3rd party library is a set of open-source digital
		standard cells at 12 track pitch height.

	--enable-osu-t15-sky130[=<path>]
		This 3rd party library is a set of open-source digital
		standard cells at 15 track pitch height.

	--enable-osu-t18-sky130[=<path>]
		This 3rd party library is a set of open-source digital
		standard cells at 18 track pitch height.

	--prefix=<path>
		This redirects the installation destination.  open_pdks
		installs into ${prefix}/share/pdk/, and by default
		${prefix} is /usr/local.  Be advised that Makefile
		automatically adds the "share/" path regardless.  To
		install in a different location, pass these (optional)
		environment variables to "make":

		SHARED_PDKS_PATH = <path>
			Overrides ${prefix}/share/pdk/ and installs
			directly into the specified <path>

		DESTDIR = <path>
			When defined, then "make install" installs into
			the specified <path>.  However, all references
			to files in the PDK will reference SHARED_PDKS_PATH.
			Use DESTDIR if you want to install into a temporary
			location such as a git repository or tarball that
			will eventually be distributed and placed at
			SHARED_PDKS_PATH on the target systems.

Step 2:
	Run:

	    make

	This will pre-process the setup files to create the PDK-specific files
	for the SKY130A PDK, and process all vendor files, and place everything
	in a local staging area.

Step 3:
	Run:

	    [sudo] make install

	The behavior of installation depends on whether or not
	--with-<pdk>-dist-path=<path> has been set (e.g.,
	--with-sky130-dist-path).  If only the local path
	(--with-<pdk>-local-path=<path>) has been set, then "make
	install" copies all files from the staging area into the
	destination.  All pointers to absolute paths in the files
	are changed to match the local path.

	If --with-<pdk>-dist-path=<path> has been set, then "make
	install" copies all files from the staging area into the
	destination as specified by the value of <path>.  All
	pointers to absolute paths in the files are changed to match
	the local path value.  The assumption is that the distribution
	path is a repository (such as a git repo) that is cloned to
	multiple hosts, and the destination on the hosts where it is
	distributed is the local path.

Step 4:
	Any time you want to check if there are updates to repositories
	that have been automatically pulled for open_pdks, Run:

		make update

	to pull any recent changes from the git repositories, and then
	rebuild the PDK.

Step 5:
	After installation, the staging area is no longer needed and can
	be removed with

		make clean
	or
		make veryclean  (also removes the log files)

	If you have not specified the installation to make symbolic links
	back to the repository sources, then the sources are no longer
	needed, either, and may be removed using

		make distclean

	However, doing so means that if the PDK needs to be updated and/or
	rebuilt, the sources will have to be re-cloned from their public
	repositories. 

	If at any time you want to remove the PDK, make sure you have run
	the "configure" script to enable the PDK you want to remove, and
	then do:

		make uninstall

-------------------------------------------------------------------------------
Summary of the installation directories:

    The Makefile script takes the source files and generates files for local
    PDK names "SKY130A", "SKY130B", etc.

    The definition of each PDK is made in the Makefile using defines; e.g.,
	-DMETAL5, etc.

    The make script makes use of the python script "preproc.py" (in the ../common
    directory) to parse each source file for "#ifdef ..."-type macros.  The syntax
    is similar to that used by the C preprocessor (cpp) but does not assume C
    language syntax in the input file, so is generally better to use than cpp
    (has less unexpected/unintentional behavior).  See comments in the preproc.py
    script for a full list of macros that it accepts (short list: #ifdef, #ifndef,
    #define, #include, and boolean operators ||, &&, and !). 

    Files generated:
	.tech		techfile for magic (full DRC, extract, GDS)
	-GDS.tech	techfile for magic, vendor mask layers
	.tcl		PDK script for magic
	-BindKeys	key binding script for magic partly matching Cadence defaults
	.magicrc	magic startup script (copy to local directory as .magicrc)
	_setup.tcl	netgen setup script for LVS
	.sh		qflow master setup script, standard 1.8V digital
	.par		graywolf setup file, standard 1.8V digital

    The installation directory below LOCAL_PATH is the name of the PDK;  e.g.,

	    sky130A/		5-metal stack with MiM cap and redistribution layer

    The installation directory hierarchy below the PDK name looks like the following:

		libs.tech/		technology and setup files

		    magic/		magic techfiles, startup file, PDK script,
					and key binding script.
		    netgen/		netgen setup file
		    qflow/		qflow scripts and graywolf setup files.
		    klayout/		setup files for klayout
		    openlane/		setup and supplementary files for openlane
		    ngspice/		base model files and libraries for ngspice
		    xschem/		setup files for xschem
		    irsim/		setup and parameter files for IRSIM

		libs.ref/		foundry data

		    cdl/		CDL netlists
		    doc/		Foundry documentation
		    gds/		GDS files
		    lef/		LEF macro files
		    lib/		Timing files
		    mag/		Magic files derived from GDS
		    maglef/		Magic files derived from LEF macros
		    spice/		SPICE netlists (ngspice compatible)
		    techlef/		LEF technology files
		    verilog/		verilog modules

    Each subdirectory of libs.ref is further divided into sections based on the
    IP type.  The section names are largely foundry-dependent.  For SkyWater Sky130,
    these sections include one or more of:

			sky130_fd_sc_hd/		1.8V digital logic (high density)
			sky130_fd_sc_hdll/		1.8V digital logic (high density low leakage)
			sky130_fd_sc_hs/		1.8V digital logic (high speed)
			sky130_fd_sc_hvl/		3.3V digital logic
			sky130_fd_sc_lp/		1.8V digital logic (low power)
			sky130_fd_sc_ls/		1.8V digital logic (low speed)
			sky130_fd_sc_ms/		3.3V digital logic (medium speed)

			sky130_fd_io/			Standard I/O

			sky130_fd_pr/			Primitive devices w/fixed layout

			sky130_ml_xx_hd/		Library of alphanumeric layouts

    The target installation destinations assume the directory structure above.  Changing
    this requires editing the source files.