The first tool to compile and install is Magic, one of the tools that can be used
for layout work, which also can perform device extraction for LVS and simulation,
and parasitic extraction for sign-off simulation. It also can read and write LEF
and DEF files, read SPICE netlists into (unwired) layout, read and write layout
GDS, make plots, and more. It is used by the open_pdks installer to build out
parts of the PDK that are not available in the sources, and so needs to be
installed and running before the PDKs can be built and installed.
Documentation:
Documentation on Magic can be found at
http://opencircuitdesign.com/magic/.
This is a front page with a number of button selections in the sidebar which lead
to various useful sub-pages. Go to Download for instructions on how to
download either the git repository sources or the source tarball.
Install has instructions for compiling and installing Magic.
Using Magic has a complete command-line command reference, and
Technology Files has a complete reference to the technology file format.
Documentation has a number of older published papers about Magic, online
translations of the manual pages for Magic, and online translations of the magic
tutorials.
There is an additional reference written by Harald Pretl called the Magic cheat
sheet which has a good summary of command-line commands and key bindings for
the beginner user. That document can be found
here
(part of OSIC-Multitools).
Download:
The best way to obtain the source code for Magic is to download it from github.
The main source repository is kept on the server at
opencircuitdesign.com;
any updates are mirrored to github overnight, so the github version is never more
than a day out of date (and is usually up-to-date). Issues should be posted on
the github site, and pull requests can be made from github as well. The source
repository is:
https://github.com/RTimothyEdwards/magic/.
Installation:
Magic should compile on all major OS versions except Windows. On Windows, the
use of
WSL
is recommended, where magic can be compiled and installed according to
the same instructions that would be used for an Ubuntu Linux system. There is a
file in the source code called
INSTALL_MacOS.md
that should be referred to when compiling on Mac OS.
Magic should be compiled with the Tcl/Tk interpreter enabled. Magic can be
compiled without interpreter support for backwards compatibility with very old
versions; this is not recommended. For a complete list of prerequisites, see
the documentation page listed above and click on Install in the sidebar,
and read the sectionSystem Requirements.
In summary, on a Linux system, the prerequisites can be installed with
apt install m4 libx11-dev tcl-dev tk-dev libcairo2-dev
and optionally, for Open-GL support, use
apt install mesa-common-dev libglu1-mesa-dev
For users of Fedora, CentOS, and similar Linux systems, the equivalent package
installer commands are:
yum install m4 libX11-devel tcl-devel tk-devel cairo-devel
and
yum install mesa-libGL mesa-libGLU
After installing prerequisites, you need to run from the command line:
./configure --enable-cairo-offscreen
make
sudo make install
Most users who want to run the OpenGL graphics interface will probably need to
enable Cairo graphics for off-screen rendering, which requires the configuration
option above, although in some cases it may not be needed. If when running Magic
with OpenGL graphics the layer icons on the right-hand side of the window appear
black or filled with random bit patterns, then Cairo off-screen rendering is
needed.
The default installation puts the executable in the path /usr/local/bin/magic
and various files needed at run-time go to /usr/local/lib/magic/. Note that
magic itself is a shell script launcher, not an executable.
Usage:
By far, the most common way to run magic is with the command line invocation
magic -d -rcfile []
Where is either OGL or XR for OpenGL or Cairo graphics, respectively. The
startup script file is determined by the PDK (see the section on PDK
installation, below). Generally, the name of a cell (which has a database file
in the .mag format) is given on the command line without the file extension.
However, other file types such as GDS files, DEF files, or Tcl scripts can also
be passed on the command line, with the file extension included.
The other common way to run magic is in batch mode, usually as part of a script,
either taking commands from standard input or from a Tcl script file:
magic -dnull -noconsole -rcfile path << EOF
(commands)
EOF
or
magic -dnull -noconsole -rcfile path script
Specific usage of Magic for layout, extraction, DRC, and other purposes will be
explained in a later section.
In this document, it will be assumed that the PDK is installed using the default
options including the default installation location. That will put the PDK files
in the path
/usr/local/share/pdk/
followed by the specific PDK name. Given these
defaults, the command line to start magic is
magic -d XR -rcfile
/usr/local/share/pdk/sky130A/libs.tech/magic/sky130A.magicrc
for the Sky130 technology, and
magic -d XR -rcfile
/usr/local/share/pdk/gf180mcuD/libs.tech/magic/gf180mcuD.magicrc
for the GF180MCU technology.
The rcfile startup script is responsible for loading the correct technology
file into magic, loading the parameterized device generator scripts, and ensuring
that any setup commands required for the technology have been applied.
Instead of writing the long command line, the startup script file can be copied
to any working directory where Magic is being used and renamed magicrc,
or a symbolic link called .magicrc can be made that points back to the
startup script in the PDK. If that is done, then magic can be started with just
magic -d XR
and the correct startup script will be applied.
Netgen is a full-featured LVS tool which can compare two netlists, either SPICE
or verilog, including combinations of the two. It is built on a Tcl interpreter
and has a command-line interface. It handles hierarchy, parallel and series
device networks, property comparison, and pin comparison.
Documentation:
Documentation on Netgen can be found at http://opencircuitdesign.com/netgen/.
This is a front page with a number of button selections in the sidebar which
lead to various useful sub-pages. Go to Download for instructions on
how to download either the git repository sources or the source tarball.
Install has instructions for compiling and installing Netgen.
Reference has information on using Netgen and a complete command-line
command reference.
Download:
The best way to obtain the source code for Netgen is to download it from github.
The main source repository is kept on the server at opencircuitdesign.com; any
updates are mirrored to github overnight, so the github version is never more
than a day out of date (and is usually up-to-date). Issues should be posted on
the github site, and pull requests can be made from github as well. The source
repository is: https://github.com/RTimothyEdwards/netgen/.
Installation:
Netgen should compile on all major OS versions except Windows. On Windows, the
use of WSL-2 is recommended, where Netgen can be compiled and installed according
to the same instructions that would be used for an Ubuntu Linux system.
Netgen should be compiled with the Tcl/Tk interpreter enabled. Netgen can be
compiled without interpreter support for backwards compatibility with very old
versions; this is not recommended. For a complete list of prerequisites, see
the documentation page listed above and click on Install in the sidebar,
and read the section System Requirements. In summary, on a Linux system,
the prerequisites can be installed with
apt install tcl-dev tk-dev
(on Ubuntu or Debian systems), or
yum install tcl-devel tk-devel
(on Fedora or CentOSD systems).
Since these are also requirements for Magic, they should already be installed.
There are generally no non-default options needed for configuration, so
installing netgen is simply
./configure
make
sudo make install
Usage:
There is a GUI version of Netgen that can be invoked with netgen -gui.
However, it is more common to run Netgen in batch mode. If the netlists are both
simple single files, then the easiest way to run netgen is with the lvs
command on the command line:
netgen -batch lvs lvs_options
If the netlists require special handling for read-in, such as reading multiple
files from different sources, or special setup, then it works best to put all
the commands into a script file and source the script file from the command line:
netgen -batch source script_file
The script file will then invoke the lvs command at the end of the script.
The arguments passed to the lvs command for a simple comparison of two
netlist files are:
lvs "netlist1 cell1" "netlist2 cell2"
setup_file output_file
Where the comes from the PDK and the is an arbitrary
name for the output log (default comp.out). For the Sky130 PDK, the
setup file is:
/usr/local/share/pdk/sky130A/libs.tech/netgen/sky130A_setup.tcl
And for the GF180MCU PDK, the setup file is:
/usr/local/share/pdk/gf180mcuD/libs.tech/netgen/gf180mcuD_setup.tcl
The setup file will be found automatically if it is copied to the local working
directory where netgen is being run and renamed to setup.tcl (or a
symbolic link can be made to the file in the PDK).
The next important step is to obtain, build, and install the open PDKs. As of
this writing, there are two open PDKs that are supported by the open_pdks
installer. These are sky130 and gf180mcu. Of all the open
source tools, only Magic is required to be installed prior to running the PDK
installer, which makes use of Magic for a number of tasks.
Each open PDK is a collection of libraries in open repositories containing files
in standard open formats like GDS, SPICE, LEF/DEF, liberty, and verilog. These
file formats are sufficient to completely describe most process libraries like
standard cells, I/O cells, and primitive devices. There are additional components
like DRC and extraction rule decks, tables of parasitic capacitance, and
parameterized cell generators that do not have standard open formats. Some of
this information is in the open PDK primary sources, and some in the open PDK
documentation. The open_pdks installer is responsible for creating a common
structure around all libraries and files; ensuring that the resulting files
are compatible with selected open source tools, and providing additional files
for open source tools when needed (such as DRC rules converted from
documentation to a format understood by magic or klayout).
Processes are often defined by a foundry as having multiple variants which all
belong to the same basic process but may involve different sets of process
options; each variant corresponds to a unique set of masks used during
fabrication. Typically, the variants will be different numbers of metal layers
available for routing, or a MiM capacitor option, or similar option. Foundries
have their own unique naming schemes for identifying a process variant. To
maintain some consistency across foundry processes, open_pdks enumerates its
own process variants by adding a suffix such as A, B, C,
etc., to the process name. The suffix string is arbitrary, but each unique
string corresponds to an entire PDK to be installed. Because most process
options do not affect all files (i.e., an extra top-level metal layer will
have little or no impact on a standard cell library), open_pdks optimizes the
installed PDK by making symbolic links from files in one process variant to
another if the contents are the same. That way, many process variants can be
created without greatly increasing the disk space needed to hold the files,
but with each process variant acting like its own self-contained PDK.
For example, the Sky130 PDK has two variants A and B defined
by open_pdks. Variant Sky130A is the standard process, and variant
Sky130B is a variant that supports the manufacture of ReRAM devices.
The GF180MCU process has four variants A, B, C, and
D. Variant GF180MCUA has three metal layers; variant
GF180MCUB has four metal layers; variant GF180MCUC has five
metal layers, and variant GF180MCUD has five metal layers with a
thicker top metal. Where examples are given in this document, the variants
Sky130A and GF180MCUD will be used unless otherwise noted.
The tool open_pdks is largely a set of scripts and Makefiles that builds out
and populates a common structure for a PDK that can be recognized by the open
source tools. The two existing open PDKs, sky130 and gf180mcu,
are known to open_pdks. Additional PDKs (open or otherwise) can be added to
open_pdks as additional subdirectories, using the same Makefile format.
Instructions on the open_pdks website are the best detailed resource for
installation. This document explains the most common install setups commonly
needed.
The open_pdks build process is a multi-step process:
- The user runs the configure script to declare which PDK(s) to install,
and can select specific libraries to ignore or extra libraries to install.
The configure process builds the Makefile that is used in the next step.
- Next, the user runs make. The first step of the make process
is to clone the necessary source repositories into the open_pdks sources
subdirectory.
- The next step of make is to completely build out the PDK for each
defined process variant, which is done in a staging area in open_pdks in
a subdirectory named for the process variant (e.g., sky130/sky130A/).
- Finally, the user runs make install. The files are copied from the
staging directory into the final install target directory, creating symbolic
links where possible to reduce disk space.
- After the build and install, the user can run make clean to remove the
contents of the staging directory, make veryclean to additionally
remove the log files generated during the build and install processes, and
make distclean to additionally remove the cloned repository sources.
It is recommended to always install and clean up the staging and source
directories to save disk space, which can be considerable for a PDK. It is
also recommended to keep the install target in a system-wide available directory
which does not have write access for typical users. The PDK contents are not
intended to be altered, and keeping them in a read-only filesystem area prevents
accidental modifications to the PDK files. It is possible to use a PDK from
the staging area prior to running make install. This is recommended
only to test the PDK; the PDK should not normally be used from the staging area.
A typical build of the Sky130 PDK looks like this:
./configure --enable-sky130-pdk --enable-sram-sky130
make
sudo make install
make distclean
A typical build of the GF180MCU PDK looks like this:
./configure --enable-gf180mcu-pdk --enable-osu-sc-gf180mcu
make
sudo make install
make distclean
While it is possible to build PDKs for multiple foundry processes (e.g., Sky130
and GF180MCU) in a single step, this is not recommended due to the large amount
of disk space used by each PDK and the amount of redundant data generated during
the cloning and staging steps. Each process can be built and installed separately.
Please note: The build process is multithreaded, and any error that occurs is
usually lost in the middle of the terminal output. The terminal output is saved
as a log file in the PDK directory (e.g., sky130/sky130A_make.log). If an error
occurs, then the Makefile will terminate with error status 2. Review the log
file; since most of the Make process is done with python scripts, errors will
usually have a python Traceback message where the error occurred.
Please also note: The build process generates a large amount of output, much
of which contains warnings and occasional errors. These messages are produced
by the tools being invoked by open_pdks and are not under the control of
open_pdks. If the Make process does not terminate with an error status, then
any error messages in the terminal output are non-fatal errors and can be ignored.
There is no single mandatory way to set up a filesystem for analog design.
Generally, though, a guiding principle should be that any component of a
design that could be valuable for re-use should exist in its own self-contained
area. Otherwise, the recommendation is that the filesystem should follow the
following structure:
top-level project directory
xschem/ magic/ lef/ gds/ netlist/ macros/
This locates most related files in a common area: Schematic and symbol files
in xschem, Magic database files in magic, abstract layout views in lef, final
layout in gds, and SPICE netlists in netlist. Where subcomponents of the
design could be independent IP, the macros directory can be populated with
symbolic links to other projects. The use of symbolic links makes the
subcomponents more portable.
Ideally, the project itself should be a git repository, to provide a robust
method of version tracking. If made into a git repository, it is recommended
that the following file types be excluded from versioning by listing them in
a .gitignore file, because they are either intermediate results or reproducible
on demand: *.ext (magic intermediate extraction files), *.raw (SPICE raw files).
macros/ should be added to .gitignore since they should be their own repositories.
