Update documentation for library

docs/source/FAQ.md

@@ -13,25 +13,25 @@ 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 too if using SCMOS)
++ `temp.gds` is the layout (.mag files too if using SCMOS)
-+ temp.sp is the netlist
++ `temp.sp` is the netlist
-+ test1.drc.err is the std err output of the DRC command
++ `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.out` is the standard output of the DRC command
-+ test1.drc.results is the DRC results file
++ `test1.drc.results` is the DRC results file
-+ test1.lvs.err is the std err output of the LVS command
++ `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.out` is the standard output of the LVS command
-+ test1.lvs.results is the DRC results file
++ `test1.lvs.results` is the DRC results file
 
 Depending on your DRC/LVS tools, there will also be:
-+ run_drc.sh is a script to run DRC
++ `run\_drc.sh` is a script to run DRC
-+ run_ext.sh is a script to run extraction
++ `run\_ext.sh` is a script to run extraction
-+ run_lvs.sh is a script to run LVS
++ `run\_lvs.sh` is a script to run LVS
 
-If DRC/LVS fails, the first thing is to check if it ran in the .out and
+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
+`.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.
 
-If DRC/LVS runs, but doesn't pass, you then should look at the .results
+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. 
 

docs/source/base_data_structures.md

@@ -7,9 +7,9 @@ This page of the documentation explains the base data structures of OpenRAM.
 
 ## Table of Contents
 1. [Design Classes](#design-classes)
-2. [Base Class Inheritance](#base-class-inheritance)
+1. [Base Class Inheritance](#base-class-inheritance)
-3. [Parameterized Transistor](#parameterized-transistor-ptx-or-pfinfet)
+1. [Parameterized Transistor](#parameterized-transistor-ptx-or-pfinfet)
-4. [Parameterized Cells](#parameterized-cells)
+1. [Parameterized Cells](#parameterized-cells)
 
 
 

docs/source/basic_setup.md

@@ -13,35 +13,55 @@ In general, the OpenRAM compiler has very few dependencies:
 + Make
 + Python 3.6 or higher
 + Various Python packages (pip install -r requirements.txt)
-+ [Git]
++ Git
+
+
+
+## OpenRAM Library
+OpenRAM is available as a Python library. There are a few ways to install it:
+
++ Install using Makefile (you need to clone the repo):
+```
+git clone git@github.com:VLSIDA/OpenRAM.git
+cd OpenRAM
+make library
+```
++ Install the latest _dev_ version:
+```
+pip3 install git+ssh://git@github.com/VLSIDA/OpenramRAM.git@dev
+```
+
 
 ## Docker
 
-We have a [docker setup](./docker) to run OpenRAM. To use this, you should run:
+We have a [docker setup](../../docker) to run OpenRAM. To use this, you should run:
 ```
 cd OpenRAM/docker
 make build
 ```
-This must be run once and will take a while to build all the tools.
+This must be run once and will take a while to build all the tools. If you have the
+OpenRAM library installed, you can also run the docker setup from the package
+installation directory.
+
 
 
 ## Environment
 
-You must set two environment variables:
+If you haven't installed the OpenRAM library or you want to use a different OpenRAM installation,
+you can set two environment variables:
 + OPENRAM\_HOME should point to the compiler source directory.
-+ OPENERAM\_TECH should point to one or more root technology directories (colon separated).
++ OPENRAM\_TECH should point to one or more root technology directories (colon separated).
 
-You should also add OPENRAM\_HOME to your PYTHONPATH.
+If you have the library installed and OPENRAM\_HOME set, the library will use the installation on
+the OPENRAM\_HOME path.
 
-For example add this to your .bashrc:
+If you don't have the library, you should also add OPENRAM\_HOME to your PYTHONPATH. This is not
+needed if you have the library.
 
+You can add these environment variables to your `.bashrc`:
 ```
   export OPENRAM_HOME="$HOME/OpenRAM/compiler"
   export OPENRAM_TECH="$HOME/OpenRAM/technology"
-```
-
-You should also add OPENRAM\_HOME to your PYTHONPATH:
-```
   export PYTHONPATH=$OPENRAM_HOME
 ```
 
@@ -51,17 +71,17 @@ directory that you use and any custom technology modules as well. For example:
   export PYTHONPATH="$OPENRAM_HOME:$OPENRAM_TECH/sky130:$OPENRAM_TECH/sky130/custom"
 ```
 
-We include the tech files necessary for [SCMOS] SCN4M_SUBM,
+We include the tech files necessary for [SCMOS] SCN4M\_SUBM,
 [FreePDK45]. The [SCMOS] spice models, however, are
 generic and should be replaced with foundry models. You may get the
 entire [FreePDK45 PDK here][FreePDK45].
 
 
+
 ### Sky130 Setup
 
-To install [Sky130], you must have the open_pdks files installed in $PDK_ROOT. 
+To install [Sky130], you must have the open\_pdks files installed in $PDK\_ROOT. 
 To install this automatically, you can run:
-
 ```
 cd $HOME/OpenRAM
 make pdk
@@ -69,8 +89,15 @@ make pdk
 
 Then you must also install the [Sky130] SRAM build space and the appropriate cell views
 by running:
-
 ```
 cd $HOME/OpenRAM
 make install
 ```
+
+You can also run these from the package installation directory if you have the OpenRAM library.
+
+
+
+[SCMOS]:    https://www.mosis.com/files/scmos/scmos.pdf
+[FreePDK45]: https://www.eda.ncsu.edu/wiki/FreePDK45:Contents
+[Sky130]:   https://github.com/google/skywater-pdk-libs-sky130_fd_bd_sram.git

docs/source/basic_usage.md

@@ -7,16 +7,19 @@ This page of the documentation explains the basic usage of OpenRAM.
 
 ## Table of Contents
 1. [Environment Variable Setup](#environment-variable-setup-assuming-bash)
-2. [Command Line Usage](#command-line-usage)
+1. [Script Usage (with library)](#script-usage-with-library)
-3. [Configuration Files](#configuration-files)
+1. [Command Line Usage (with library)](#command-line-usage-with-library)
-4. [Common Configuration File Options](#common-configuration-file-options)
+1. [Command Line Usage (without library)](#command-line-usage-without-library)
-5. [Output Files](#output-files)
+1. [Configuration Files](#configuration-files)
-6. [Data Sheets](#data-sheets)
+1. [Common Configuration File Options](#common-configuration-file-options)
+1. [Output Files](#output-files)
+1. [Data Sheets](#data-sheets)
 
 
 
 ## Environment Variable Setup (assuming bash)
-* OPENRAM_HOME defines where the compiler directory is
+> **Note**: This is optional if you have the OpenRAM library. See [basic setup](./basic_setup.md#go-back) for details.
+* OPENRAM\_HOME defines where the compiler directory is
     * ```export OPENRAM_HOME="$HOME/openram/compiler"```
 * OPENRAM_TECH defines list of paths where the technologies exist
     * `export OPENRAM_TECH="$HOME/openram/technology"`
@@ -27,14 +30,41 @@ This page of the documentation explains the basic usage of OpenRAM.
 
 
 
-## Command Line Usage
+## Script Usage (with library)
+If you have the library installed, you can use OpenRAM in any Python script. You can import "openram" as follows:
+```python
+import openram
+import globals
+globals.init_openram("myconfig.py") # Config files are explained on this page
+```
+Note that you should import "openram" in this order so that the modules are imported properly. You can also look
+at `sram_compiler.py` as an example on how to use "openram."
+
+
+
+## Command Line Usage (with library)
+You can run OpenRAM from the command line  using the `sram_compiler.py` script that is included in the
+library's installation. You can the package directory on a path like:
+```
+/home/mrg/.local/lib/python3.8/site-packages/openram
+```
+
+Alternatively, you can run the following command to find that path:
+```
+echo -e "import os\nimport openram\nprint(os.path.dirname(openram.__file__))" | python3 -
+```
+
+You can continue with following section for more details.
+
+
+## Command Line Usage (without library)
 
 Once you have defined the environment, you can run OpenRAM from the command line
 using a single configuration file written in Python.
 
 For example, create a file called *myconfig.py* specifying the following
 parameters for your memory:
-```
+```python
 # Data word size
 word_size = 2
 # Number of words in the memory
@@ -65,7 +95,7 @@ output_name = "sram_{0}_{1}_{2}".format(word_size,num_words,tech_name)
 
 You can then run OpenRAM by executing:
 ```
-python3 $OPENRAM_HOME/openram.py myconfig
+python3 $OPENRAM_HOME/../sram_compiler.py myconfig
 ```
 You can see all of the options for the configuration file in
 $OPENRAM\_HOME/options.py

docs/source/bitcells.md

@@ -7,8 +7,8 @@ This page of the documentation explains the bitcells supported by OpenRAM.
 
 ## Table of Contents
 1. [Multiport Bitcells](#multiport-bitcells)
-2. [Relative Bitcell Sizes](#relative-bitcell-sizes-035um-scmos)
+1. [Relative Bitcell Sizes](#relative-bitcell-sizes-035um-scmos)
-3. [Thin SRAM Bitcells](#thin-sram-bitcells-130nm)
+1. [Thin SRAM Bitcells](#thin-sram-bitcells-130nm)
 
 
 

docs/source/characterization.md

@@ -6,19 +6,19 @@ This page of the documentation explains the characterization of OpenRAM.
 
 
 ## Table of Contents
-1.  [Characterization Overview](#characterization-overview)
+1. [Characterization Overview](#characterization-overview)
-2.  [Characterizer Organization](#characterizer-organization)
+1. [Characterizer Organization](#characterizer-organization)
-3.  [Characterization Options](#characterization-options)
+1. [Characterization Options](#characterization-options)
-4.  [Characterization Measurements](#characterization-measurements)
+1. [Characterization Measurements](#characterization-measurements)
-5.  [Analytical Characterization](#analytical-characterization)
+1. [Analytical Characterization](#analytical-characterization)
-6.  [Multiport Characterization](#multiport-characterization)
+1. [Multiport Characterization](#multiport-characterization)
-7.  [Characterizer Unit Test Use](#characterizer-unit-test-use)
+1. [Characterizer Unit Test Use](#characterizer-unit-test-use)
-8.  [Functional Simulation](#functional-simulation)
+1. [Functional Simulation](#functional-simulation)
-9.  [Power/Delay Characterization](#powerdelay-characterization)
+1. [Power/Delay Characterization](#powerdelay-characterization)
-10. [Timing Graph](#timing-graph)
+1. [Timing Graph](#timing-graph)
-11. [Graph Creation Example: Buffer](#graph-creation-example-buffer)
+1. [Graph Creation Example: Buffer](#graph-creation-example-buffer)
-12. [Graph Module Exclusion](#graph-module-exclusion)
+1. [Graph Module Exclusion](#graph-module-exclusion)
-13. [Timing Measurement Checks](#timing-measurement-checks)
+1. [Timing Measurement Checks](#timing-measurement-checks)
 
 
 
@@ -62,9 +62,9 @@ Measures the timing/power through SPICE simulation:
 
 ## Characterization Measurements
 * Characterization is performed primarily to generate tables in .lib file
-    * cell_rise/cell_fall - Delay of from negative clock edge to DOUT when reading a 1 or 0 respectively
+    * cell\_rise/cell\_fall - Delay of from negative clock edge to DOUT when reading a 1 or 0 respectively
-    * rise_transition/fall_transition - Slew of DOUT when read 1 or 0 respectively
+    * rise\_transition/fall\_transition - Slew of DOUT when read 1 or 0 respectively
-    * Setup and hold time for inputs (setup_rising, hold_rising)
+    * Setup and hold time for inputs (setup\_rising, hold\_rising)
     * Total power and leakage power
     * Delays and slews and intended to be independent of clock period.
     * Fall delays are copied to rise delays after characterization*

docs/source/control_logic.md

@@ -7,13 +7,13 @@ This page of the documentation explains the control logic and timing of OpenRAM.
 
 ## Table of Contents
 1. [Read Timing](#read-timing)
-2. [Write Timing](#write-timing)
+1. [Write Timing](#write-timing)
-3. [External Control Signals](#external-control-signals)
+1. [External Control Signals](#external-control-signals)
-4. [Internal Control Signals](#internal-control-signals)
+1. [Internal Control Signals](#internal-control-signals)
-5. [Replica Bitline (RBL)](#replica-bitline-rbl)
+1. [Replica Bitline (RBL)](#replica-bitline-rbl)
-6. [Internal Control Signals Diagram (Read)](#internal-control-signals-diagram-read)
+1. [Internal Control Signals Diagram (Read)](#internal-control-signals-diagram-read)
-7. [Internal Control Signals Diagram (Write)](#internal-control-signals-diagram-write)
+1. [Internal Control Signals Diagram (Write)](#internal-control-signals-diagram-write)
-8. [Clock Distribution](#clock-distribution)
+1. [Clock Distribution](#clock-distribution)
 
 
 

docs/source/debug.md

@@ -7,11 +7,11 @@ This page of the documentation explains the debugging and unit testing of OpenRA
 
 ## Table of Contents
 1. [Unit Tests](#unit-tests)
-2. [Unit Test Organization](#unit-test-organization)
+1. [Unit Test Organization](#unit-test-organization)
-3. [Running Unit Tests](#running-unit-tests)
+1. [Running Unit Tests](#running-unit-tests)
-4. [Successful Unit Tests](#successful-unit-tests)
+1. [Successful Unit Tests](#successful-unit-tests)
-5. [Debugging Unsuccessful Unit Tests](#debugging-unsuccessful-unit-tests-or-openrampy)
+1. [Debugging Unsuccessful Unit Tests](#debugging-unsuccessful-unit-tests-or-sram_compilerpy)
-6. [Temporary Output Files](#temporary-output-files)
+1. [Temporary Output Files](#temporary-output-files)
 
 
 
@@ -124,7 +124,7 @@ OK
 
 
 
-## Debugging Unsuccessful Unit Tests (or openram.py)
+## Debugging Unsuccessful Unit Tests (or sram\_compiler.py)
 * You will get an ERROR during unit test and see a stack trace 
 * Examine the temporary output files in the temp directory (/tmp/mydir)
 ```console

docs/source/design_modules.md

@@ -6,17 +6,17 @@ This page of the documentation explains the hierarchical design modules of OpenR
 
 
 ## Table of Contents
-1.  [Hierarchical Design Modules](#hierarchical-design-modules-1)
+1. [Hierarchical Design Modules](#hierarchical-design-modules-1)
-2.  [Bank](#bank)
+1. [Bank](#bank)
-3.  [Port Data](#port-data)
+1. [Port Data](#port-data)
-4.  [Port Address](#port-address)
+1. [Port Address](#port-address)
-5.  [Plain Bitcell Array](#plain-bitcell-array)
+1. [Plain Bitcell Array](#plain-bitcell-array)
-6.  [Variations of Bitcells Needed](#variations-of-bitcells-needed)
+1. [Variations of Bitcells Needed](#variations-of-bitcells-needed)
-7.  [Replica Bitcell Array](#replica-bitcell-array)
+1. [Replica Bitcell Array](#replica-bitcell-array)
-8.  [1D Arrays](#1d-arrays)
+1. [1D Arrays](#1d-arrays)
-9.  [2D Arrays](#2d-arrays)
+1. [2D Arrays](#2d-arrays)
-10. [Delay Line](#delay-line)
+1. [Delay Line](#delay-line)
-11. [Hierarchical (Address) Decoder](#hierarchical-address-decoder)
+1. [Hierarchical (Address) Decoder](#hierarchical-address-decoder)
 
 
 
@@ -61,7 +61,7 @@ This page of the documentation explains the hierarchical design modules of OpenR
 
 ## Port Address
 * Encapsulates the row decoder and wordline driver for easier placement next to a bank
-* Each port will have its own port_address module 
+* Each port will have its own port\_address module 
 
 
 

docs/source/index.md

@@ -6,15 +6,15 @@ These pages provide the documentation of OpenRAM. You can use the links below to
 
 
 ## Table of Contents
-1.  [OpenRAM Dependencies](#openram-dependencies)
+1. [OpenRAM Dependencies](#openram-dependencies)
-1.  [Supported Technologies](#supported-technologies)
+1. [Supported Technologies](#supported-technologies)
-1.  [Basic Setup](./basic_setup.md#go-back)
+1. [Basic Setup](./basic_setup.md#go-back)
-1.  [Basic Usage](./basic_usage.md#go-back)
+1. [Basic Usage](./basic_usage.md#go-back)
-1.  [Bitcells](./bitcells.md#go-back)
+1. [Bitcells](./bitcells.md#go-back)
-1.  [Architecture](./architecture.md#go-back)
+1. [Architecture](./architecture.md#go-back)
-1.  [Implementation](#implementation)
+1. [Implementation](#implementation)
-1.  [Technology and Tool Portability](#technology-and-tool-portability)
+1. [Technology and Tool Portability](#technology-and-tool-portability)
-1.  [Tutorials](./tutorials.md#go-back)
+1. [Tutorials](./tutorials.md#go-back)
 1. [Debugging and Unit Testing](./debug.md#go-back)
 1. [Technology Setup](./technology_setup.md#go-back)
 1. [Library Cells](./library_cells.md#go-back)
@@ -25,13 +25,12 @@ These pages provide the documentation of OpenRAM. You can use the links below to
 1. [Characterization](./characterization.md#go-back)
 1. [Results](./results.md#go-back)
 1. [FAQ](./FAQ.md#go-back)
-1.  [Contributors/Collaborators](#contributorscollaborators)
+1. [Contributors/Collaborators](#contributorscollaborators)
 
 
 
 
 ## OpenRAM Dependencies
-
 Please see the Dockerfile for the required versions of tools.
 
 In general, the OpenRAM compiler has very few dependencies:
@@ -39,16 +38,16 @@ In general, the OpenRAM compiler has very few dependencies:
 + Make
 + Python 3.6 or higher
 + Various Python packages (pip install -r requirements.txt)
-+ [Git]
++ Git
 
 Commercial tools (optional):
 * Spice Simulator
     * Hspice  I-2013.12-1 (or later)
     * CustomSim 2017 (or later)
 * DRC
-    * Calibre 2017.3_29.23
+    * Calibre 2017.3\_29.23
 * LVS
-    * Calibre 2017.3_29.23
+    * Calibre 2017.3\_29.23
 
 
 
@@ -56,7 +55,7 @@ Commercial tools (optional):
 * NCSU FreePDK 45nm
     * Non-fabricable but contains DSM rules
     * Calibre or klayout for DRC/LVS
-* MOSIS 0.35um (SCN4M_SUBM)
+* MOSIS 0.35um (SCN4M\_SUBM)
     * Fabricable technology
     * Magic/Netgen or Calibre for DRC/LVS
 * Skywater 130nm (sky130)

docs/source/library_cells.md

@@ -7,12 +7,12 @@ This page of the documentation explains the library cells of OpenRAM.
 
 ## Table of Contents
 1. [Required Hard/Custom Cells](#required-hardcustom-cells)
-2. [Bitcell(s)](#bitcells)
+1. [Bitcell(s)](#bitcells)
-3. [Multiport Bitcells](#multiport-bitcells)
+1. [Multiport Bitcells](#multiport-bitcells)
-4. [Parameterized Bitcell](#parameterized-bitcell)
+1. [Parameterized Bitcell](#parameterized-bitcell)
-5. [Sense Amplifier](#sense-amplifier)
+1. [Sense Amplifier](#sense-amplifier)
-6. [DFF](#dff)
+1. [DFF](#dff)
-7. [Tristate/Write Driver](#tristatewrite-driver)
+1. [Tristate/Write Driver](#tristatewrite-driver)
 
 
 

docs/source/results.md

@@ -6,13 +6,13 @@ This page of the documentation explains the results of OpenRAM.
 
 
 ## Table of Contents
-1.  [Small Layouts](#small-layouts)
+1. [Small Layouts](#small-layouts)
-2.  [Relative Planar Bitcells](#relative-planar-bitcells-035um-scmos)
+1. [Relative Planar Bitcells](#relative-planar-bitcells-035um-scmos)
-3.  [SRAM Area](#sram-area)
+1. [SRAM Area](#sram-area)
-4.  [Generated Layout by OpenRAM](#generated-layout-by-openram-for-a-multiport-6r2w-sram-in-32-nm-soi-cmos-technology)
+1. [Generated Layout by OpenRAM](#generated-layout-by-openram-for-a-multiport-6r2w-sram-in-32-nm-soi-cmos-technology)
-5.  [Timing and Density Results for Generated SRAMs](#timing-and-density-results-for-generated-srams)
+1. [Timing and Density Results for Generated SRAMs](#timing-and-density-results-for-generated-srams)
-6.  [Comparison with Fabricated SRAMs](#comparison-with-fabricated-srams)
+1. [Comparison with Fabricated SRAMs](#comparison-with-fabricated-srams)
-7.  [Conclusions](#conclusions)
+1. [Conclusions](#conclusions)
 
 
 

docs/source/routing.md

@@ -7,9 +7,9 @@ This page of the documentation explains the routing of OpenRAM.
 
 ## Table of Contents
 1. [Power Supply Options](#power-supply-options)
-2. [Power Routing](#power-routing)
+1. [Power Routing](#power-routing)
-3. [Power Supply Algorithm](#power-supply-algorithm)
+1. [Power Supply Algorithm](#power-supply-algorithm)
-4. [Channel Router](#channel-router)
+1. [Channel Router](#channel-router)
 
 
 

docs/source/technology_setup.md

@@ -7,17 +7,17 @@ This page of the documentation explains the technology setup of OpenRAM.
 
 ## Table of Contents
 1. [Technology Directories](#technology-directories)
-2. Technology Configuration:
+1. Technology Configuration:
     1. [Layer Map](#technology-configuration-layer-map)
-    2. [GDS](#technology-configuration-gds)
+    1. [GDS](#technology-configuration-gds)
-    3. [DRC](#technology-configuration-drc)
+    1. [DRC](#technology-configuration-drc)
-    4. [SPICE](#technology-configuration-spice)
+    1. [SPICE](#technology-configuration-spice)
-    5. [Parameters](#technology-configuration-parameters)
+    1. [Parameters](#technology-configuration-parameters)
 
 
 
 ## Technology Directories
-* Environment variable OPENRAM_TECH specifies list of technology directories
+* Environment variable OPENRAM\_TECH specifies list of technology directories
     * Similar to `*nix $PATH`
 * Directory structure:
     ```
@@ -73,7 +73,7 @@ This page of the documentation explains the technology setup of OpenRAM.
 
 
 ## Technology Configuration: DRC
-* Creates the design_rule class with several parts:
+* Creates the design\_rule class with several parts:
     * Grid size
     * Location of DRC, LVS, PEX rules and layer map
     * Subset of design rules for FEOL and BEOL