From a09ff8c3583f7b815182f2d34b69050e891abaa7 Mon Sep 17 00:00:00 2001 From: Matt Guthaus Date: Wed, 17 May 2017 10:27:05 -0700 Subject: [PATCH] Updated README --- README | 297 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 250 insertions(+), 47 deletions(-) diff --git a/README b/README index 23b68c0b..ccf848a2 100644 --- a/README +++ b/README @@ -1,8 +1,11 @@ ############################################################################### BASIC SETUP --The OpenRAM compiler has very few dependencies: +- 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 +-The OpenRAM compiler has very few dependencies: 1) ngspice-26 or later or HSpice I-2013.12-1 or later 2) Python 2.7 and higher (currently excludes Python 3 and up) 3) a setup script for each technology @@ -11,21 +14,84 @@ BASIC SETUP - 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: +For example, in bash, add to your .bashrc: -export OPENRAM_HOME="$HOME/OpenRAM/compiler" -export OPENRAM_TECH="$HOME/OpenRAM/technology" + 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: +environment variable point to the PDK. +For example, in bash, add to your .bashrc: -export FREEPDK45="/bsoe/software/design-kits/FreePDK45" + 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 + + +############################################################################### +DIRECTORY STRUCTURE + +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 + + +############################################################################### +UNIT TESTS + +Regression testing performs a number of tests for all modules in OpenRAM. + +Use the command: + + python regress.py + +To run a specific test: + + python {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 + +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. + +A regression daemon script that can be used with cron is included: + + regress_daemon.py + regress_daemon.sh + +This updates a git repository, checks out code, and sends an email +report with status information. + +############################################################################### +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: -$OPENRAM_TECH/setup_scripts/setup_openram_freepdk45.py + $OPENRAM_TECH/setup_scripts/setup_openram_freepdk45.py Each setup script should be named as: setup_openram_{tech name}.py. @@ -41,7 +107,7 @@ minimum this includes: replica_cell_6t.gds tri_gate.gds -2) sp_lib folder with all the .sp (premade) library netlists for the above cells. +2) sp_lib folder with all the .sp (premade) library netlists for the above cells. 3) layers.map @@ -49,58 +115,195 @@ minimum this includes: References in tech.py to spice models DRC/LVS rules needed for dynamic cells and routing Layer information - Etc. - -- In order to debug, it is useful to have a GDS viewer. In addition to -normal layout tools, we recommend the following viewers: - -LayoutEditor http://www.layouteditor.net/ -GLADE http://www.peardrop.co.uk/ -Magic http://opencircuitdesign.com/magic/ + etc. ############################################################################### -DIRECTORY STRUCTURE +DEBUGGING -compiler - openram compiler itself (pointed to by OPENRAM_HOME) -compiler/characterizer - timing characterization code -compiler/gdsMill - gds reader/writer -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 +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: +* _calibreDRC.rul_ is the DRC rule file. +* dc_runset is the command file for caliber. +* temp.gds is the layout +* test1.drc.err is the std err output of the command +* test1.drc.out is the standard output of the command +* test1.drc.db is the DRC results file + +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 .db +file. If the DRC fails, it will typically show you the command that was used +to run caliber. It is something like this: + + calibre -gui -drc /tmp/openram_mrg_28781_temp/drc_runset -batch 2> + /tmp/openram_mrg_28781_temp/test1.drc.err 1> + /tmp/openram_mrg_28781_temp/test1.drc.out + +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 Caliber Errors + +select the .db file from calibre. + +It is possible to use other viewers as well, such as: + + LayoutEditor http://www.layouteditor.net/ + Magic http://opencircuitdesign.com/magic/ ############################################################################### -UNIT TESTS +CONTRIBUTING TO OPENRAM -Regression testing performs a number of tests for all modules in OpenRAM. +How to get the code and add contributions to OpenRAM. -Steps to run regression testing: -1) First, ensure your setup_scripts is correctly setup. -2) Navigate to the compiler directory: cd $OPENRAM_HOME -3) Use the command: - python tests/regress.py -4) To run a specific test: - python tests/{unit test}.py +0) One time, create a GitHub account. -The unit tests take the same arguments as openram.py itself. +1) Create a fork of the OpenRAM project on the github web page: -To increase the verbosity of the test, add one (or more) -v options: -python tests/00_code_format_check_test.py -v -t freepdk45 + https://github.com/mguthaus/OpenRAM -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. - -A regression daemon script that can be used with cron is included: -regress_daemon.py -regress_daemon.sh - -This updates a git repository, checks out code, and sends an email -report with status information. +It is on the upper right and says "Fork": This will make your own +OpenRAM repository on GitHub in your account. +2) Clone your repository (or use an existing cloned copy if you've +already done this once): + git clone https://github.com//OpenRAM.git + cd OpenRAM + +3) Set up a new upstream that points to MY OpenRAM repository that you +forked (only first time): + git remote add upstream https://github.com/mguthaus/OpenRAM.git + +You now have two remotes for this project: +origin which points to your GitHub fork of the project. You can read +and write to this remote. +upstream which points to the main project's GitHub repository. You can +only read from this remote. + +You can remove remotes with + git remote remove upstream +if you previously added the one with the git@github that required +authentication. + +4) Make your own branch. The number one rule is to put each piece of +work on its own branch: + git checkout -b useful-branch-name + +Note that this is shorthand for: + git branch useful-branch-name + git checkout useful-branch-name + +"master" is the name of the branch that is the release version of the +code (in your fork of the repository). You can check out the released +code with "git checkout master" or go back to your ranch with +"gitcheckout useful-branch-name". + +5) Edit your code and make commits like normal: + git add + + git commit -m "Useful comment" + +OR (sparingly, to commit all changes): + git status + + git commit -a -m "Useful comment" + +Run the unit tests entirely. Fix all bugs. + +6) After you are done (or while you are editing and you see changes in +MY master branch) make sure you have the most recent from MY master +and merge any changes. Pull the updated copy from MY master branch in +MY repository: + git pull upstream master + +This is important because we may have had other updates that conflict +with your changes and you must resolve them with current state of +master (the released, working code). You may have to merge changes if +they overlap your changes, so do this often to avoid the problem. You +now need to push this to the master of YOUR forked repository as well: + git push origin master +if you are on your master branch. Otherwise, just git push. + + +7) Push your branch to YOUR repository: + git push -u origin useful-branch-name + +Remember origin is your copy on github and useful-branch-name is the +branch that you made to contain all your changes. + +The -u flag links this branch with the remote one, so that in the +future, you can simply type git push origin. + +8) When you are done, go to GitHub and you will see a button to notify +me. Press the button and it will notify me of your pushed branch. +This will have you fill in a form for the contribution that gets sent +to me. + +9) I will review the request and may have you fix stuff if the tests +don't pass, you didn't merge all my changes in master from other +contributions, or your style of code is bad. + +10) Go back to step 3 for your next contribution. Remember, you can +push/pull work to your repository all the time and can pull from my +master as well. Make sure to add large features so that You don't have +to add lots of pull requests. ############################################################################### Example to output/input .gds layout files from/to Cadence