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..1a193703 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,27 @@ -# BASIC SETUP +# OpenRAM +[![pipeline status](https://scone.soe.ucsc.edu:8888/mrg/PrivateRAM/badges/dev/pipeline.svg?private_token=ynB6rSFLzvKUseoBPcwV)](https://github.com/VLSIDA/PrivateRAM/commits) +[![Download](images/download.svg)](https://github.com/VLSIDA/PrivateRAM/archive/dev.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. + +# 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) 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] or [SCMOS]) ++ [Magic] + [Netgen] (for [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,10 +34,10 @@ 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 [FreePDK45] and [SCMOS]. The [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 +If you are using [FreePDK45], you should also have that set up and have the environment variable point to the PDK. For example, in bash, add to your .bashrc: ``` @@ -43,16 +47,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] -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], you should install [Magic] and [Netgen]. +We have included the SCN4M design rules from [Qflow]. -# DIRECTORY STRUCTURE +# Directory Structure * compiler - openram compiler itself (pointed to by OPENRAM_HOME) * compiler/base - base data structure modules @@ -65,48 +65,52 @@ We have included the SCN4M design rules from QFlow: * compiler/router - router for signals and power supplies * 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/freepdk45 - example configuration library for [FreePDK45 technology node + * technology/scn4m_subm - example configuration library [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. Use the command: ``` - python regress.py + python3 regress.py ``` To run a specific test: ``` - python {unit test}.py + python3 {unit test}.py ``` 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 + python3 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 -example of what is needed for OpenRAM: +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 + +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: ``` $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 +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: @@ -124,115 +128,36 @@ Each specific technology (e.g., freepdk45) should be a subdirectory * Layer information * etc. -# DEBUGGING +# Get Involved -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 ++ Report bugs by submitting a [Github issue]. ++ 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] -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) +# License -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. +OpenRAM is licensed under the [BSD 3-clause License](./LICENSE). -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. +# Contributors & Acknowledgment -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 issues]: https://github.com/PrivateRAM/PrivateRAM/issues +[Github pull request]: https://github.com/PrivateRAM/PrivateRAM/pulls +[Github projects]: https://github.com/PrivateRAM/PrivateRAM/projects +[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 +[Ngspice]: http://ngspice.sourceforge.net/ +[OpenRAMpaper]: https://ieeexplore.ieee.org/document/7827670/ diff --git a/images/download.svg b/images/download.svg new file mode 100644 index 00000000..95d978ed --- /dev/null +++ b/images/download.svg @@ -0,0 +1,2 @@ + +download download latestlatest 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