luke
/
OpenRAM
mirror of https://github.com/VLSIDA/OpenRAM.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated README

This commit is contained in:
Matt Guthaus 2017-05-17 10:27:05 -07:00
parent b16dd80088
commit a09ff8c358
1 changed files with 250 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

285
README
View File

@ -1,8 +1,11 @@
############################################################################### ###############################################################################
BASIC SETUP 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 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) 2) Python 2.7 and higher (currently excludes Python 3 and up)
3) a setup script for each technology 3) a setup script for each technology
@ -11,16 +14,79 @@ BASIC SETUP
- You must set two environment variables: OPENRAM_HOME should point to - You must set two environment variables: OPENRAM_HOME should point to
the compiler source directory. OPENERAM_TECH should point to a root the compiler source directory. OPENERAM_TECH should point to a root
technology directory that contains subdirs of all other technologies. 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_HOME="$HOME/OpenRAM/compiler"
export OPENRAM_TECH="$HOME/OpenRAM/technology" 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 - 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 <techname>" 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 -All setup scripts should be in the setup_scripts directory under the
$OPENRAM_TECH directory. Please look at the following file for an $OPENRAM_TECH directory. Please look at the following file for an
example of what is needed for OpenRAM: example of what is needed for OpenRAM:
@ -49,58 +115,195 @@ minimum this includes:
References in tech.py to spice models References in tech.py to spice models
DRC/LVS rules needed for dynamic cells and routing DRC/LVS rules needed for dynamic cells and routing
Layer information Layer information
Etc. etc.
- In order to debug, it is useful to have a GDS viewer. In addition to ###############################################################################
normal layout tools, we recommend the following viewers: 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:
* _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/ LayoutEditor http://www.layouteditor.net/
GLADE http://www.peardrop.co.uk/
Magic http://opencircuitdesign.com/magic/ Magic http://opencircuitdesign.com/magic/
###############################################################################
DIRECTORY STRUCTURE
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
############################################################################### ###############################################################################
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: 0) One time, create a GitHub account.
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
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: https://github.com/mguthaus/OpenRAM
python tests/00_code_format_check_test.py -v -t freepdk45
To specify a particular technology use "-t <techname>" such as It is on the upper right and says "Fork": This will make your own
"-t scn3me_subm". The default for a unit test is freepdk45 whereas OpenRAM repository on GitHub in your account.
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.
2) Clone your repository (or use an existing cloned copy if you've
already done this once):
git clone https://github.com/<youruser>/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 <new files>
<edit files>
git commit -m "Useful comment" <files changed>
OR (sparingly, to commit all changes):
git status
<check that all the changed files are correct and should be commited>
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 Example to output/input .gds layout files from/to Cadence