diff --git a/README.md b/README.md
index 58c8e505f..78282ac6b 100644
--- a/README.md
+++ b/README.md
@@ -1,234 +1,215 @@
-# BASIC SETUP
+# OpenRAM
+Master: [![pipeline status](https://scone.soe.ucsc.edu:8888/mrg/OpenRAM/badges/master/pipeline.svg?private_token=ynB6rSFLzvKUseoBPcwV)](https://github.com/VLSIDA/OpenRAM/commits)
+Dev: [![pipeline status](https://scone.soe.ucsc.edu:8888/mrg/OpenRAM/badges/dev/pipeline.svg?private_token=ynB6rSFLzvKUseoBPcwV)](https://github.com/VLSIDA/OpenRAM/commits)
+[![Download](images/download.svg)](https://github.com/VLSIDA/OpenRAM/archive/master.zip)
+[![License: BSD 3-clause](./images/license_badge.svg)](./LICENSE)
-Please look at the OpenRAM ICCAD paper and presentation in the repository:
-https://github.com/mguthaus/OpenRAM/blob/master/OpenRAM_ICCAD_2016_paper.pdf
-https://github.com/mguthaus/OpenRAM/blob/master/OpenRAM_ICCAD_2016_presentation.pdf
+An open-source static random access memory (SRAM) compiler.
-The OpenRAM compiler has very few dependencies:
-* ngspice-26 (or later) or HSpice I-2013.12-1 (or later) or CustomSim 2017 (or later)
-* Python 2.7 and higher (currently excludes Python 3 and up)
-* Python numpy
-* a setup script for each technology
-* a technology directory for each technology with the base cells
-
-If you want to perform DRC and LVS, you will need either:
-* Calibre (for FreePDK45 or SCMOS)
-* Magic + Netgen (for SCMOS only)
+# What is OpenRAM?
-You must set two environment variables: OPENRAM_HOME should point to
-the compiler source directory. OPENERAM_TECH should point to a root
-technology directory that contains subdirs of all other technologies.
-For example, in bash, add to your .bashrc:
-```
- export OPENRAM_HOME="$HOME/OpenRAM/compiler"
- export OPENRAM_TECH="$HOME/OpenRAM/technology"
-```
-For example, in csh/tcsh, add to your .cshrc/.tcshrc:
-```
- setenv OPENRAM_HOME "$HOME/OpenRAM/compiler"
- setenv OPENRAM_TECH "$HOME/OpenRAM/technology"
-```
-If you are using FreePDK, you should also have that set up and have the
-environment variable point to the PDK.
-For example, in bash, add to your .bashrc:
-```
- export FREEPDK45="/bsoe/software/design-kits/FreePDK45"
-```
-For example, in csh/tcsh, add to your .tcshrc:
-```
- setenv FREEPDK45 "/bsoe/software/design-kits/FreePDK45"
-```
-We do not distribute the PDK, but you may get it from:
- https://www.eda.ncsu.edu/wiki/FreePDK45:Contents
+
-If you are using SCMOS, you should install Magic and netgen from:
- http://opencircuitdesign.com/magic/
- http://opencircuitdesign.com/netgen/
-In addition, you will need to install the MOSIS SCMOS rules for scn3me_subm
-that are part of QFlow:
- http://opencircuitdesign.com/qflow/
+OpenRAM is an open-source Python framework to create the layout,
+netlists, timing and power models, placement and routing models, and
+other views necessary to use SRAMs in ASIC design. OpenRAM supports
+integration in both commercial and open-source flows with both
+predictive and fabricable technologies.
-# DIRECTORY STRUCTURE
+# Basic Setup
-* compiler - openram compiler itself (pointed to by OPENRAM_HOME)
- * compiler/characterizer - timing characterization code
- * compiler/gdsMill - GDSII reader/writer
- * compiler/router - detailed router
- * compiler/tests - unit tests
-* technology - openram technology directory (pointed to by OPENRAM_TECH)
- * technology/freepdk45 - example configuration library for freepdk45 technology node
- * technology/scn3me_subm - example configuration library SCMOS technology node
- * technology/setup_scripts - setup scripts to customize your PDKs and OpenRAM technologies
+The OpenRAM compiler has very few dependencies:
++ [Ngspice] 26 (or later) or HSpice I-2013.12-1 (or later) or CustomSim 2017 (or later)
++ Python 3.5 or higher
++ Python numpy (pip3 install numpy to install)
++ flask_table (pip3 install flask to install)
+If you want to perform DRC and LVS, you will need either:
++ Calibre (for [FreePDK45])
++ [Magic] + [Netgen] (for [SCMOS])
-# UNIT TESTS
+You must set two environment variables:
++ OPENRAM\_HOME should point to the compiler source directory.
++ OPENERAM\_TECH should point to a root technology directory.
-Regression testing performs a number of tests for all modules in OpenRAM.
+For example add this to your .bashrc:
-Use the command:
-```
- python regress.py
-```
-To run a specific test:
```
- python {unit test}.py
+ export OPENRAM_HOME="$HOME/openram/compiler"
+ export OPENRAM_TECH="$HOME/openram/technology"
```
-The unit tests take the same arguments as openram.py itself.
-To increase the verbosity of the test, add one (or more) -v options:
-```
- python tests/00_code_format_check_test.py -v -t freepdk45
-```
-To specify a particular technology use "-t " such as
-"-t scn3me_subm". The default for a unit test is freepdk45 whereas
-the default for openram.py is specified in the configuration file.
+We include the tech files necessary for [FreePDK45] and [SCMOS]
+SCN4M_SUBM. The [SCMOS] spice models, however, are generic and should
+be replaced with foundry models. If you are using [FreePDK45], you
+should also have that set up and have the environment variable point
+to the PDK. For example add this to your .bashrc:
-A regression daemon script that can be used with cron is included in
-a separate repository at https://github.com/mguthaus/openram-daemons
```
- regress_daemon.py
- regress_daemon.sh
+ export FREEPDK45="/bsoe/software/design-kits/FreePDK45"
```
-This updates a git repository, checks out code, and sends an email
-report with status information.
-# CREATING CUSTOM TECHNOLOGIES
+You may get the entire [FreePDK45 PDK here][FreePDK45].
+If you are using [SCMOS], you should install [Magic] and [Netgen].
+We have included the most recent SCN4M_SUBM design rules from [Qflow].
-All setup scripts should be in the setup_scripts directory under the
-$OPENRAM_TECH directory. Please look at the following file for an
-example of what is needed for OpenRAM:
-```
- $OPENRAM_TECH/setup_scripts/setup_openram_freepdk45.py
-```
-Each setup script should be named as: setup_openram_{tech name}.py.
+# Basic Usage
-Each specific technology (e.g., freepdk45) should be a subdirectory
-(e.g., $OPENRAM_TECH/freepdk45) and include certain folders and files:
- 1. gds_lib folder with all the .gds (premade) library cells. At a
- minimum this includes:
- * ms_flop.gds
- * sense_amp.gds
- * write_driver.gds
- * cell_6t.gds
- * replica_cell_6t.gds
- * tri_gate.gds
- 2. sp_lib folder with all the .sp (premade) library netlists for the above cells.
- 3. layers.map
- 4. A valid tech Python module (tech directory with __init__.py and tech.py) with:
- * References in tech.py to spice models
- * DRC/LVS rules needed for dynamic cells and routing
- * Layer information
- * etc.
+Once you have defined the environment, you can run OpenRAM from the command line
+using a single configuration file written in Python. You may wish to add
+$OPENRAM\_HOME to your $PYTHONPATH.
-# DEBUGGING
+For example, create a file called *myconfig.py* specifying the following
+parameters for your memory:
-When OpenRAM runs, it puts files in a temporary directory that is
-shown in the banner at the top. Like:
-```
- /tmp/openram_mrg_18128_temp/
```
-This is where simulations and DRC/LVS get run so there is no network
-traffic. The directory name is unique for each person and run of
-OpenRAM to not clobber any files and allow simultaneous runs. If it
-passes, the files are deleted. If it fails, you will see these files:
-* temp.gds is the layout
-* (.mag files if using SCMOS)
-* temp.sp is the netlist
-* test1.drc.err is the std err output of the DRC command
-* test1.drc.out is the standard output of the DRC command
-* test1.drc.results is the DRC results file
-* test1.lvs.err is the std err output of the LVS command
-* test1.lvs.out is the standard output of the LVS command
-* test1.lvs.results is the DRC results file
+# Data word size
+word_size = 2
+# Number of words in the memory
+num_words = 16
-Depending on your DRC/LVS tools, there will also be:
-* _calibreDRC.rul_ is the DRC rule file (Calibre)
-* dc_runset is the command file (Calibre)
-* extracted.sp (Calibre)
-* run_lvs.sh is a Netgen script for LVS (Netgen)
-* run_drc.sh is a Magic script for DRC (Magic)
-* .spice (Magic)
+# Technology to use in $OPENRAM\_TECH
+tech_name = "scn4m_subm"
+# Process corners to characterize
+process_corners = ["TT"]
+# Voltage corners to characterize
+supply_voltages = [ 3.3 ]
+# Temperature corners to characterize
+temperatures = [ 25 ]
-If DRC/LVS fails, the first thing is to check if it ran in the .out and
-.err file. This shows the standard output and error output from
-running DRC/LVS. If there is a setup problem it will be shown here.
+# Output directory for the results
+output_path = "temp"
+# Output file base name
+output_name = "sram_{0}_{1}_{2}".format(word_size,num_words,tech_name)
-If DRC/LVS runs, but doesn't pass, you then should look at the .results
-file. If the DRC fails, it will typically show you the command that was used
-to run Calibre or Magic+Netgen.
-
-To debug, you will need a layout viewer. I prefer to use Glade
-on my Mac, but you can also use Calibre, Magic, etc.
-
-1. Calibre
+# Disable analytical models for full characterization (WARNING: slow!)
+# analytical_delay = False
+```
- Start the Calibre DESIGNrev viewer in the temp directory and load your GDS file:
+You can then run OpenRAM by executing:
```
- calibredrv temp.gds
+python3 $OPENRAM\_HOME/openram.py myconfig
```
- Select Verification->Start RVE and select the results database file in
- the new form (e.g., test1.drc.db). This will start the RVE (results
- viewer). Scroll through the check pane and find the DRC check with an
- error. Select it and it will open some numbers to the right. Double
- click on any of the errors in the result browser. These will be
- labelled as numbers "1 2 3 4" for example will be 4 DRC errors.
+You can see all of the options for the configuration file in
+$OPENRAM\_HOME/options.py
- In the viewer ">" opens the layout down a level.
-2. Glade
+# Unit Tests
- You can view errors in Glade as well. I like this because it is on my laptop.
- You can get it from: http://www.peardrop.co.uk/glade/
+Regression testing performs a number of tests for all modules in OpenRAM.
+From the unit test directory ($OPENRAM\_HOME/tests),
+use the following command to run all regression tests:
- To remote display over X windows, you need to disable OpenGL acceleration or use vnc
- or something. You can disable by adding this to your .bashrc in bash:
```
- export GLADE_USE_OPENGL=no
+ python3 regress.py
```
- or in .cshrc/.tcshrc in csh/tcsh:
+To run a specific test:
```
- setenv GLADE_USE_OPENGAL no
+ python3 {unit test}.py
```
- To use this with the FreePDK45 or SCMOS layer views you should use the
- tech files. Then create a .glade.py file in your user directory with
- these commands to load the technology layers:
+The unit tests take the same arguments as openram.py itself.
+
+To increase the verbosity of the test, add one (or more) -v options:
```
-ui().importCds("default",
-"/Users/mrg/techfiles/freepdk45/display.drf",
-"/Users/mrg/techfiles/freepdk45/FreePDK45.tf", 1000, 1,
-"/Users/mrg/techfiles/freepdk45/layers.map")
+ python3 tests/00_code_format_check_test.py -v -t freepdk45
```
- Obviously, edit the paths to point to your directory. To switch
- between processes, you have to change the importCds command (or you
- can manually run the command each time you start glade).
-
- To load the errors, you simply do Verify->Import Calibre Errors select
- the .results file from Calibre.
-
-3. Magic
-
- Magic is only supported in SCMOS. You will need to install the MOSIS SCMOS rules
- and Magic from: http://opencircuitdesign.com/
+To specify a particular technology use "-t " such as
+"-t freepdk45" or "-t scn4m\_subm". The default for a unit test is scn4m_subm.
+The default for openram.py is specified in the configuration file.
- When running DRC or extraction, OpenRAM will load the GDS file, save
- the .ext/.mag files, and export an extracted netlist (.spice).
-4. It is possible to use other viewers as well, such as:
- * LayoutEditor http://www.layouteditor.net/
+# Porting to a New Technology
+If you want to support a enw technology, you will need to create:
++ a setup script for each technology you want to use
++ a technology directory for each technology with the base cells
-# Example to output/input .gds layout files from/to Cadence
+All setup scripts should be in the setup\_scripts directory under the
+$OPENRAM\_TECH directory. We provide two technology examples for
+[SCMOS] and [FreePDK45]. Please look at the following file for an
+example of what is needed for OpenRAM:
-1. To create your component layouts, you should stream them to
- individual gds files using our provided layermap and flatten
- cells. For example,
-```
- strmout -layerMap layers.map -library sram -topCell $i -view layout -flattenVias -flattenPcells -strmFile ../gds_lib/$i.gds
-```
-2. To stream a layout back into Cadence, do this:
```
- strmin -layerMap layers.map -attachTechFileOfLib NCSU_TechLib_FreePDK45 -library sram_4_32 -strmFile sram_4_32.gds
+ $OPENRAM_TECH/setup_scripts/setup_openram_freepdk45.py
```
- When you import a gds file, make sure to attach the correct tech lib
- or you will get incorrect layers in the resulting library.
+Each setup script should be named as: setup\_openram\_{tech name}.py.
+
+Each specific technology (e.g., [FreePDK45]) should be a subdirectory
+(e.g., $OPENRAM_TECH/freepdk45) and include certain folders and files:
+* gds_lib folder with all the .gds (premade) library cells:
+ * dff.gds
+ * sense_amp.gds
+ * write_driver.gds
+ * cell_6t.gds
+ * replica\_cell\_6t.gds
+* sp_lib folder with all the .sp (premade) library netlists for the above cells.
+* layers.map
+* A valid tech Python module (tech directory with __init__.py and tech.py) with:
+ * References in tech.py to spice models
+ * DRC/LVS rules needed for dynamic cells and routing
+ * Layer information
+ * Spice and supply information
+ * etc.
+
+# Get Involved
+
++ Report bugs by submitting [Github issues].
++ Develop new features (see [how to contribute](./CONTRIBUTING.md))
++ Submit code/fixes using a [Github pull request]
++ Follow our [project][Github projects].
++ Read and cite our [ICCAD paper][OpenRAMpaper]
+
+# Further Help
+
++ [Additional hints](./HINTS.md)
++ [OpenRAM Slack Workspace][Slack]
++ [OpenRAM Users Group][user-group] ([subscribe here][user-group-subscribe])
++ [OpenRAM Developers Group][dev-group] ([subscribe here][dev-group-subscribe])
+
+# License
+
+OpenRAM is licensed under the [BSD 3-clause License](./LICENSE).
+
+# Contributors & Acknowledgment
+
+- [Matthew Guthaus] from [VLSIDA] created the OpenRAM project and is the lead architect.
+- [James Stine] from [VLSIARCH] co-founded the project.
+- Hunter Nichols maintains and updates the timing characterization.
+- Michael Grims created and maintains the multiport netlist code.
+- Jennifer Sowash is creating the OpenRAM IP library.
+- Jesse Cirimelli-Low created the datasheet generation.
+- Samira Ataei created early multi-bank layouts and control logic.
+- Bin Wu created early parameterized cells.
+- Yusu Wang is porting parameterized cells to new technologies.
+- Brian Chen created early prototypes of the timing characterizer.
+- Jeff Butera created early prototypes of the bank layout.
+
+* * *
+
+[Matthew Guthaus]: https://users.soe.ucsc.edu/~mrg
+[James Stine]: https://ece.okstate.edu/content/stine-james-e-jr-phd
+[VLSIDA]: https://vlsida.soe.ucsc.edu
+[VLSIARCH]: https://vlsiarch.ecen.okstate.edu/
+[OpenRAMpaper]: https://ieeexplore.ieee.org/document/7827670/
+
+[Github issues]: https://github.com/OpenRAM/OpenRAM/issues
+[Github pull request]: https://github.com/OpenRAM/OpenRAM/pulls
+[Github projects]: https://github.com/OpenRAM/OpenRAM/projects
+
+[email me]: mailto:mrg+openram@ucsc.edu
+[dev-group]: mailto:openram-dev-group@ucsc.edu
+[user-group]: mailto:openram-user-group@ucsc.edu
+[dev-group-subscribe]: mailto:openram-dev-group+subscribe@ucsc.edu
+[user-group-subscribe]: mailto:openram-user-group+subscribe@ucsc.edu
+
+[Magic]: http://opencircuitdesign.com/magic/
+[Netgen]: http://opencircuitdesign.com/netgen/
+[Qflow]: http://opencircuitdesign.com/qflow/history.html
+[Ngspice]: http://ngspice.sourceforge.net/
+
+[OSUPDK]: https://vlsiarch.ecen.okstate.edu/flow/
+[FreePDK45]: https://www.eda.ncsu.edu/wiki/FreePDK45:Contents
+[SCMOS]: https://www.mosis.com/files/scmos/scmos.pdf
+
+[Slack]: https://join.slack.com/t/openram/shared_invite/enQtNDgxMjc3NzU5NTI1LTE4ODMyM2I0Mzk2ZmFiMjgwYTYyMTQ4NTgwMmUwMDhiM2E1MDViNDRjYzU1NjJhZTQxNWZjMzE3M2FlODBmZjA
diff --git a/images/SCMOS_16kb_sram.jpg b/images/SCMOS_16kb_sram.jpg
new file mode 100644
index 000000000..0dda0b08b
Binary files /dev/null and b/images/SCMOS_16kb_sram.jpg differ
diff --git a/images/download.svg b/images/download.svg
new file mode 100644
index 000000000..95d978ed6
--- /dev/null
+++ b/images/download.svg
@@ -0,0 +1,2 @@
+
+
diff --git a/images/license_badge.svg b/images/license_badge.svg
new file mode 100644
index 000000000..bc36cde74
--- /dev/null
+++ b/images/license_badge.svg
@@ -0,0 +1 @@
+
\ No newline at end of file