Updates to intro and overview. Some edits to tech and DRC/LVS section.

docs/implementation.tex

@@ -315,19 +315,33 @@ OpenRAM, the default technology is FreePDK45, which has it own
 technolony directory in the trunk.  The technology-specific directory
 should consist of the following:
 \begin{itemize}
+\item Technology Setup FIle - In \verb|/techdir/setup_scripts|, there
+  should be a Python file that sets up the PDK and defines anything
+  necessary for a given technology. This file should be named
+  \verb|setup_openram_<techname>.py| where techname is the name used
+  to identify it in configuration scripts.
 \item Technology-Specific Parameters - These parameters should include
   layer numbers and any design rules that may be needed for generating
   dynamic designs (DRC rules). The parameters should be added in
-  \verb|/techdir/tech/tech.py| and layer map in the \verb|/techdir|.
+  \verb|techname/tech/tech.py| and optinally in a \verb|techname/layer.map| for
+  DRC/LVS streaming. 
 \item Library Cells - The library cells and corresponding spice
-  netlists should be added to the \verb|/gds_lib| and \verb|/sp_lib|
-  directories.
-\item Portation Functions - Some of the dynamically generated cells
-  may need helper functions to deal with technology-specific
-  requirements.  Additional, tech-specific, functions should be added
-  to the \verb|/techdir|.
+  netlists should be added to the \verb|techname/gds_lib| and
+  \verb|techname/sp_lib| directories.
+\item Spice Models - If models are not supplied in the PDK, they can be
+  placed in the technology directory as done in SCMOS.
 \end{itemize}
 
+The height and width of library cells is determined by the bounding
+box of all geometries. Sometimes this is not desired, for example,
+when a rail must be shared. In this case, the boundary layer in the
+technology file is used to define the height and width of the cell.
+
+Pins are recognized in library cells by the largest rectangle that
+encloses the pin label text. Multiple pins with the same name are
+supported.  Pins with the same name such as gnd are assumed to be
+``must connect'' which requires that they later be connected.
+
 For more information regarding the technology directory and how to set
 one up for a new technology, refer to Section~\ref{sec:porting}
 
@@ -342,30 +356,32 @@ the command line. The \verb|DRC_LVS()| function saves a GDSII file and a Spice
 file into a temporary directory and then calls two functions to
 perform DRC and LVS that are tool-dependent.
 
-A reference implementation for the DRC and LVS functions are provided
-for Cadence Calibre since this is the most common DRC/LVS tool. Each
-of these functions generates a batch-mode ``runset'' file which
-contains the options to correctly run DRC and LVS. The functions then
-parse the batch mode output for any potential errors and returns the
-number of errors encountered.
+Wrapper implementation for DRC and LVS functions are provided for the
+open-source tools Magic+Netgen and the commercial tool, Cadence
+Calibre.  Each of these functions generates a batch-mode script or runset
+file which contains the options to correctly run DRC and LVS. The
+functions then parse the batch mode output for any potential errors
+and returns the number of errors encountered.
 
 The function \verb|run_drc()| requires a cell name and a GDSII
 file. The cell name corresponds to the top level cell in the GDSII
-file. It also uses the layer map file for the technology to correctly
-import the GDSII file into the Cadence database to perform DRC. The
-function returns the number of DRC violations. 
+file. For Calibre, it also uses the layer map file for the technology
+to correctly import the GDSII file into the Cadence database to
+perform DRC. The function returns the number of DRC violations.
 
 The function \verb|run_lvs()| requires a cell name, a GDSII file, and
-a Spice file. Calibre will extract an extracted Spice netlist from the
-GDSII file and will then compare this netlist with the OpenRAM Spice
-netlist. The function returns the number of uncompared and unmatched
-devices/nets in the design.
+a Spice file. Magic or Calibre will extract an extracted Spice netlist
+from the GDSII file and will then compare this netlist with the
+OpenRAM Spice netlist. The function returns the number of errors
+encountered if there is an LVS mismatch.
+
 
 For both DRC and LVS, the summary file and other report files are left
 in the OpenRAM temporary directory after DRC/LVS is run. These report
 files can be examined to further understand why errors were
-encountered. In addition, by increasing the debug level, the command
-line to re-create the DRC/LVS check can be obtained and run manually.
+encountered. In addition, by increasing the debug level with one or
+more ``-v'' command-line parametres, the command to re-create the
+DRC/LVS check can be obtained and run manually.
 
 
 

docs/intro.tex

@@ -20,12 +20,9 @@ The specific features of OpenRAM are:
 
 \item \textbf{Memory Array Generation} 
 
-  Currently, OpenRAM supports simple 1 read/write port synchronous
-  memories, but it will be extended to multi-port memories, register
-  files, and asynchronous memories in the future. The generation
-  includes features such as automatic word-line driver sizing,
-  efficient decoder sizing, multiple-word column support, and
-  self-timing with replica bitlines.
+  Currently, OpenRAM includes features such as automatic word-line
+  driver sizing, efficient decoder sizing, multiple-word column
+  support, and self-timing with replica bitlines.
 
 \item \textbf{Portability and Extensibility} 
 
@@ -41,11 +38,11 @@ The specific features of OpenRAM are:
   to distribute the technology information of others commercial
   technologies soon.
 
-  OpenRAM makes calls to commercial circuit simulators and DRC/LVS
-  tools in an abstracted way for circuit simulation and
-  verification. This enables adaptation to other design
-  methodologies. However, it also supports a completely open-source
-  platform for older technologies.
+  OpenRAM makes calls to both open-source or commercial circuit
+  simulators and DRC/LVS tools in an abstracted way for circuit
+  simulation and verification. This enables adaptation to other design
+  methodologies. It supports a completely open-source
+  platform for older SCMOS technologies.
 
 \item \textbf{Timing and Power Characterization}
 
@@ -74,7 +71,9 @@ The specific features of OpenRAM are:
 
 \subsection{Requirements}
 
-Development is done on Ubuntu or MacOS systems with Python 2.7.
+Development is done on Ubuntu or MacOS systems with Python 2.7. It
+requires a few common Python libraries such as numpy, scipy (soon, for
+optimization) along with standard Python libraries (os, sys, etc.).
 
 
 \subsubsection{Timing Verification Tools}
@@ -92,7 +91,7 @@ OpenRAM can use the following circuit simulators and possibly others
 if they support the Spice3 file format:
 \begin{itemize}
   \item HSpice I-2013.12-1 or later
-  \item ngSpice 26 \url{http://ngspice.sourceforge.net/}
+  \item ngspice 26 \url{http://ngspice.sourceforge.net/}
   \item CustomSim (xa) M-2017.03-SP5 or later
 \end{itemize}
 
@@ -119,14 +118,15 @@ LVS can be done with:
 
 \subsubsection{Technology Files}
 
-To work with FreePDK45, you must install the FreePDK baseline kit from:
+To work with FreePDK45, you must install the FreePDK baseline kit from:\\
 \url{https://www.eda.ncsu.edu/wiki/FreePDK45:Contents}
 
 We have included an example Calibre DRC deck for MOSIS SCMOS design
-rules, but DRC with Magic relies on its own design rules:
-\url{https://www.mosis.com/files/scmos/scmos.pdf} We require the
-format 32 or later to enable stacked vias which is included with
-Qflow:
+rules, but DRC with Magic relies on the MOSIS scalable design
+rules:\\
+\url{https://www.mosis.com/files/scmos/scmos.pdf}.\\
+We require the format 32 or later to enable stacked vias which is
+included with Qflow:
 \begin{verbatim}
 git clone http://opencircuitdesign.com/qflow
 cp tech/osu050/SCN3ME_SUBM.30.tech <your magic tech lib>
@@ -137,15 +137,19 @@ DRCLVS\_HOME environment variable.
 
 \subsubsection{Spice Models}
 
-FreePDK45 comes with a spice device model. Once this is installed, it
-is used.
+FreePDK45 comes with a spice device model. Once this is installed and
+the PDK\_DIR environment variable for FreePDK45 is set, these spice
+models are used.
 
 SCMOS, however, does not come with a device spice model. This must be
 obtained from MOSIS or another vendor. We use the ON Semiconductor
-0.5um device models.
+0.5um device models, but are unable to distribute them. We have included our
+own generic spice models for simulation of SCMOS, but we recommend that
+you replace these with more accurate foundry models.
 
 You can over-ride the location of the spice models with the
-SPICE\_MODEL\_DIR environment variable.
+SPICE\_MODEL\_DIR environment variable to ensure that they do not
+``creep'' into the OpenRAM git repository.
 
 
 
@@ -156,7 +160,7 @@ to make it relocatable in a variety of user scenarios. Specifically,
 the user may want technology directories that are separate from
 OpenRAM. Or, the user may want to have several versions of
 OpenRAM. This is done with the folowing required environment
-variables: specifically:
+variables:
 \begin{itemize}
 \item OPENRAM\_HOME defines the location of the compiler source directory.
 \item OPENRAM\_TECH defines the location of the OpenRAM technology
@@ -165,12 +169,12 @@ variables: specifically:
 
 Other environmental variables and additional required paths for
 specific technologies are dynamically added during runtime by sourcing
-a technology setup script. These are located in the
+a technology setup script. These are mostly PDK-specific. These are located in the
 "\$OPENRAM\_TECH/setup\_scripts" directory. Example scripts for SCMOS and
-FreePDK45 are included with the distribution. These setup any things
-needed by the PDK.
+FreePDK45 are included with the distribution. 
 
-\subsection{Design Flow}
+
+%\subsection{Design Flow}
 
 %% % high-level org
 
@@ -209,13 +213,14 @@ needed by the PDK.
 
 \subsection{Usage}
 
-The OpenRAM compiler rquires a single argument of a configuration
+The OpenRAM compiler requires a single argument of a configuration
 file. The configuration file specifies, at a minimum, the memory size
 parameters in terms of the number of words, word size (in bits), and
 number of banks. By default, OpenRAM will chose the number of columns
-to make the memory reasonably square. Commonly, the configuration file
-also includes parameters for the output path, base output file name,
-and technology of an SRAM.
+to make the memory reasonably square. Other common configuration
+parameters are the output path and base filename, characterization
+corners (including the supply voltage), number of ports, technology
+node, etc.
 
 The configuration file can be used to over-ride any option in the
 options.py file.  Many of these can also be controlled by the command-line

docs/modules.tex

@@ -10,17 +10,25 @@ of the possible circuits that can be adapted into a SRAM architecture;
 refer to Section~\ref{sec:implementation} for more information on
 adding different module designs to the compiler.
 
-Each module has a corresponding python class in the \verb|compiler|
-directory.  These classes are used to generate both the GDSII layout
-and spice netlists. Each module can consist of library cells as
-discussed in Section~\ref{sec:techdir}, paramterized cells in
-Section~\ref{sec:parameterized} or other modules.  A discussion of the
-design hierarchy and how to implement a module is provided in
-Section~\ref{sec:design}.
+Data structures for schematic and layout are provided in the
+\verb|base| directory. These implement a generic design object and
+have many auxiliary functions for routing, pin access, placement,
+DRC/LVS, etc.  These are discussed further in
+Section~\ref{sec:implementation}.
+
+Each module has a corresponding Python class in the
+\verb|compiler/modules| directory.  These classes are used to generate
+both the GDSII layout and spice netlists. A module can consist of
+hard library cells (Section~\ref{sec:techdir}), paramterized
+cells (Section~\ref{sec:parameterized}) or other modules.
 
 When combining modules at any level of hierarchy, DRC rules for
 minimum spacing of metals, wells, etc. must be followed and DRC and
-LVS are run by default after each hierarchical module's creation.
+LVS are run by default after each hierarchical module's creation. A
+module is responsible for creating its own pins to enable routing
+at the next level up in the hierarchy. A module must also define its
+height and width assuming a (0,0) offset for the lower-left coordinate
+to aid with placement.
 
 
 \subsection{The Bitcell and Bitcell Array}

docs/openram_manual.tex

@@ -25,7 +25,6 @@
 
 \title{OpenRAM Manual}
 \author{Matthew R. Guthaus - mrg@ucsc.edu\\
-  James Stine - james.stine@okstate.edu\\
   and many others
 }
 %\renewcommand{\today}{October 14, 2010}

docs/overview.tex

@@ -49,9 +49,11 @@ The inputs to the SRAM are:
 \item CSb - Active-low Chip Select
 \item WEb - Active-low Write Enable
 \item OEb - Active-low Output Enable
-\item ADDR\# - corresponds to the Address Bus input, labeled 0 to N-address bits.
-\item DATA\# - corresponds to the bi-directional Data bus.
+\item ADDR[\#] - Address Bus input (LSB is 0)
+\item DATA[\#] - Bi-directional Data bus (LBS is 0)
 \end{itemize}
+If multiple ports are used, the ADDR and DATA buses are appended with
+integers to extend them.
 
 The outputs to the SRAM are: 
 \begin{itemize}
@@ -59,33 +61,30 @@ The outputs to the SRAM are:
 \item DATA\# - correspond to the bi-directional Data bus.
 \end{itemize}
 
+The supply voltages to the SRAM are:
+\begin{itemize}
+\item vdd - Supply voltage
+\item gnd - Ground supply voltage
+\end{itemize}
 
 \subsection{Top-Level SRAM Module}
 \label{sec:sram}
 
-The \verb|sram| class in \verb|sram.py| is the top-level SRAM module.
-This class handles the overall organization of the memory and the
-input/output signals.  Based on the user inputs, the various bus and
-array sizes are calculated and passed to the \verb|bank| module.
-All other sub-modules access the value of sizes from \verb|bank|. 
-The overall organization is depicted in
-Figure~\ref{fig:sram_architecture}, discussion of the design data
-structure is discussed in Section~\ref{sec:design} and the modules
-contained in the top-level SRAM are detailed in
-Section~\ref{sec:modules}.
-
-When the user has specified the desired size (word size, total
-number of words and number of banks) of the memory that is to be generated, 
-the following parameters must be calculated. There are several constraints 
-to be considered in this calculations:
-
-(i) \verb|sram| can generate 1 bank, 2 banks or 4 banks.
-
-(ii) The area of each bank should be as square as possible which is dependent on the area of a 6T cell.
-
-(iii) There are several options for multiplexing (column-mux): 2-way, 4-way, 8-way  and none.
+The sram class in \verb|sram.py| is the top-level SRAM module.  This
+class handles the overall organization of the memory, instantiates the
+contorl logic, instantiates a number of banks, and creates decoded
+enable signals for multiple banks. All of the top level routing is
+performed in the sram class.
 
 
-All of the top level routing is performed in the \verb|sram| class.
+The sram class instantiates identical copies of the bank module from
+\verb|bank.py|.  All other sub-modules access the value of sizes from
+bank.  The bank module includes an address decoder, (optional) column
+address decoder, (optional) column mux, sense amplifiers, precharge
+circuitry, write drivers, etc.  A single bank organization is depicted
+in Figure~\ref{fig:sram_architecture}.
+
+Discussion of the design data structure is discussed in
+Section~\ref{sec:design} and the modules contained in the top-level
+SRAM are detailed in Section~\ref{sec:modules}.
 
-\fixme{More soon...}