diff --git a/HINTS.md b/HINTS.md new file mode 100644 index 00000000..b12704e5 --- /dev/null +++ b/HINTS.md @@ -0,0 +1,110 @@ +# Debugging + +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 too 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 + +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) + +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. + +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 + + Start the Calibre DESIGNrev viewer in the temp directory and load your GDS file: +``` + calibredrv temp.gds +``` + 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. + + In the viewer ">" opens the layout down a level. + +2. Glade + + 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/ + + 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 +``` + or in .cshrc/.tcshrc in csh/tcsh: +``` + setenv GLADE_USE_OPENGAL no +``` + 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: +``` +ui().importCds("default", +"/Users/mrg/techfiles/freepdk45/display.drf", +"/Users/mrg/techfiles/freepdk45/FreePDK45.tf", 1000, 1, +"/Users/mrg/techfiles/freepdk45/layers.map") +``` + 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/ + + 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/ + + +# Example to output/input .gds layout files from/to Cadence + +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 +``` + When you import a gds file, make sure to attach the correct tech lib + or you will get incorrect layers in the resulting library. diff --git a/README.md b/README.md index b486823b..7824b9d2 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,28 @@ -# BASIC SETUP +# OpenRAM +[![pipeline status](https://scone.soe.ucsc.edu:8888/mrg/PrivateRAM/badges/dev/pipeline.svg)](https://scone.soe.ucsc.edu:8888/mrg/PrivateRAM/commits/dev) +[![License: BSD 3-clause](./image/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. + +# Why OpenRAM? + + +# Basic Setup 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 and higher -* Python numpy (pip3 install numpy to install) -* flask_table (pip3 install flask to install) -* a setup script for each technology you want to use -* a technology directory for each technology with the base cells ++ ngspice-26 (or later) or HSpice I-2013.12-1 (or later) or CustomSim 2017 (or later) ++ Python 3.5 and higher ++ Python numpy (pip3 install numpy to install) ++ flask_table (pip3 install flask to install) ++ a setup script for each technology you want to use ++ a technology directory for each technology with the base cells (comes with [SCMOS][SCMOS] and [FreePDK45][FreePDK45]) If you want to perform DRC and LVS, you will need either: -* Calibre (for FreePDK45 or SCMOS) -* Magic + Netgen (for SCMOS only) ++ Calibre (for [FreePDK45][FreePDK45] or [SCMOS][SCMOS]) ++ Magic + Netgen (for [SCMOS][SCMOS] only) -You must set two environment variables: OPENRAM_HOME should point to -the compiler source directory. OPENERAM_TECH should point to a root +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: ``` @@ -30,7 +35,7 @@ For example, in csh/tcsh, add to your .cshrc/.tcshrc: setenv OPENRAM_TECH "$HOME/openram/technology" ``` -We include the tech files necessary for FreePDK and SCMOS. The SCMOS +We include the tech files necessary for FreePDK and [SCMOS][SCMOS]. The [SCMOS][SCMOS] spice models, however, are generic and should be replaced with foundry models. If you are using FreePDK, you should also have that set up and have the @@ -43,16 +48,12 @@ 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 +We do not distribute the PDK, but you may download [FreePDK45][FreePDK45] -If you are using SCMOS, you should install Magic and netgen from: - http://opencircuitdesign.com/magic/ - http://opencircuitdesign.com/netgen/ -We have included the SCN4M design rules from QFlow: - http://opencircuitdesign.com/qflow/ +If you are using [SCMOS][SCMOS], you should install [Magic][Magic] and [Netgen][Netgen]. +We have included the SCN4M design rules from [Qflow][Qflow]. -# DIRECTORY STRUCTURE +# Directory Structure * compiler - openram compiler itself (pointed to by OPENRAM_HOME) * compiler/base - base data structure modules @@ -66,14 +67,14 @@ We have included the SCN4M design rules from QFlow: * compiler/tests - unit tests * technology - openram technology directory (pointed to by OPENRAM_TECH) * technology/freepdk45 - example configuration library for freepdk45 technology node - * technology/scn4m_subm - example configuration library SCMOS technology node + * technology/scn4m_subm - example configuration library [SCMOS][SCMOS] technology node * technology/scn3me_subm - unsupported configuration (not enough metal layers) * technology/setup_scripts - setup scripts to customize your PDKs and OpenRAM technologies * docs - LaTeX manual (outdated) * lib - IP library of pregenerated memories -# UNIT TESTS +# Unit Tests Regression testing performs a number of tests for all modules in OpenRAM. @@ -92,19 +93,19 @@ 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 freepdk45" or "-t scn4m_subm". The default for a unit test is scn4m_subm. +"-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. -# CREATING CUSTOM TECHNOLOGIES +# Creating Custom Technologies -All setup scripts should be in the setup_scripts directory under the -$OPENRAM_TECH directory. Please look at the following file for an +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. +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: @@ -124,115 +125,28 @@ Each specific technology (e.g., freepdk45) should be a subdirectory * Layer information * etc. -# DEBUGGING +# License -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 +OpenRAM is licensed under the [BSD 3-clause License](./LICENSE). -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) +# Contributors & Acknowledgment -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. - -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 - - Start the Calibre DESIGNrev viewer in the temp directory and load your GDS file: -``` - calibredrv temp.gds -``` - 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. - - In the viewer ">" opens the layout down a level. - -2. Glade - - 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/ - - 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 -``` - or in .cshrc/.tcshrc in csh/tcsh: -``` - setenv GLADE_USE_OPENGAL no -``` - 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: -``` -ui().importCds("default", -"/Users/mrg/techfiles/freepdk45/display.drf", -"/Users/mrg/techfiles/freepdk45/FreePDK45.tf", 1000, 1, -"/Users/mrg/techfiles/freepdk45/layers.map") -``` - 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/ - - 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/ +- [Matthew Guthaus][Matthew Guthaus] created the OpenRAM project and is the lead architect. -# Example to output/input .gds layout files from/to Cadence - -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 -``` - When you import a gds file, make sure to attach the correct tech lib - or you will get incorrect layers in the resulting library. +* * * +[Matthew Guthaus]: https://users.soe.ucsc.edu/~mrg +[Github releases]: https://github.com/PrivateRAM/PrivateRAM/releases +[Github issues]: https://github.com/PrivateRAM/PrivateRAM/issues +[Github pull requests]: https://github.com/PrivateRAM/PrivateRAM/pulls +[Github projects]: https://github.com/PrivateRAM/PrivateRAM/projects +[Github insights]: https://github.com/PrivateRAM/PrivateRAM/pulse +[email me]: mailto:mrg+openram@ucsc.edu +[VLSIDA]: https://vlsida.soe.ucsc.edu +[OSUPDK]: https://vlsiarch.ecen.okstate.edu/flow/ +[Magic]: http://opencircuitdesign.com/magic/ +[Netgen]: http://opencircuitdesign.com/netgen/ +[Qflow]: http://opencircuitdesign.com/qflow/history.html +[FreePDK45]: https://www.eda.ncsu.edu/wiki/FreePDK45:Contents +[SCMOS]: https://www.mosis.com/files/scmos/scmos.pdf diff --git a/images/license-badge.svg b/images/license-badge.svg new file mode 100644 index 00000000..bc36cde7 --- /dev/null +++ b/images/license-badge.svg @@ -0,0 +1 @@ + LicenseLicenseBSD 3-ClauseBSD 3-Clause \ No newline at end of file