diff --git a/README.md b/README.md index 52ab52c7..f289af6d 100644 --- a/README.md +++ b/README.md @@ -19,169 +19,8 @@ predictive and fabricable technologies. # Documentation -Please take a look at our presentation We have created a detailed -presentation that serves as our [documentation][documentation]. -This is the most up-to-date information, so please let us know if you see -things that need to be fixed. - -# Basic Setup - -## Dependencies - -Please see the Dockerfile for the required versions of tools. - -In general, the OpenRAM compiler has very few dependencies: -+ Docker -+ Make -+ Python 3.6 or higher -+ Various Python packages (pip install -r requirements.txt) -+ [Git] - -## Docker - -We have a [docker setup](./docker) to run OpenRAM. To use this, you should run: -``` -cd OpenRAM/docker -make build -``` -This must be run once and will take a while to build all the tools. - - -## Environment - -You must set two environment variables: -+ OPENRAM\_HOME should point to the compiler source directory. -+ OPENERAM\_TECH should point to one or more root technology directories (colon separated). - -You should also add OPENRAM\_HOME to your PYTHONPATH. - -For example add this to your .bashrc: - -``` - export OPENRAM_HOME="$HOME/OpenRAM/compiler" - export OPENRAM_TECH="$HOME/OpenRAM/technology" -``` - -You should also add OPENRAM\_HOME to your PYTHONPATH: -``` - export PYTHONPATH=$OPENRAM_HOME -``` - -Note that if you want symbols to resolve in your editor, you may also want to add the specific technology -directory that you use and any custom technology modules as well. For example: -``` - export PYTHONPATH="$OPENRAM_HOME:$OPENRAM_TECH/sky130:$OPENRAM_TECH/sky130/custom" -``` - -We include the tech files necessary for [SCMOS] SCN4M_SUBM, -[FreePDK45]. The [SCMOS] spice models, however, are -generic and should be replaced with foundry models. You may get the -entire [FreePDK45 PDK here][FreePDK45]. - - -### Sky130 Setup - -To install [Sky130], you must have the open_pdks files installed in $PDK_ROOT. -To install this automatically, you can run: - -``` -cd $HOME/OpenRAM -make pdk -``` - -Then you must also install the [Sky130] SRAM build space and the appropriate cell views -by running: - -``` -cd $HOME/OpenRAM -make install -``` - -# Basic Usage - -Once you have defined the environment, you can run OpenRAM from the command line -using a single configuration file written in Python. - -For example, create a file called *myconfig.py* specifying the following -parameters for your memory: -``` -# Data word size -word_size = 2 -# Number of words in the memory -num_words = 16 - -# Technology to use in $OPENRAM_TECH -tech_name = "scn4m_subm" - -# You can use the technology nominal corner only -nominal_corner_only = True -# Or you can specify particular corners -# Process corners to characterize -# process_corners = ["SS", "TT", "FF"] -# Voltage corners to characterize -# supply_voltages = [ 3.0, 3.3, 3.5 ] -# Temperature corners to characterize -# temperatures = [ 0, 25 100] - -# Output directory for the results -output_path = "temp" -# Output file base name -output_name = "sram_{0}_{1}_{2}".format(word_size,num_words,tech_name) - -# Disable analytical models for full characterization (WARNING: slow!) -# analytical_delay = False - -``` - -You can then run OpenRAM by executing: -``` -python3 $OPENRAM_HOME/openram.py myconfig -``` -You can see all of the options for the configuration file in -$OPENRAM\_HOME/options.py - -To run designs in Docker, it is suggested to use, for example: -``` -cd OpenRAM/macros -make example_config_scn4m_subm -``` - -# Unit Tests - -Regression testing performs a number of tests for all modules in OpenRAM. -From the unit test directory ($OPENRAM\_HOME/tests), -use the following command to run all regression tests: - -``` -cd OpenRAM/compiler/tests -make -j 3 -``` -The -j can run with 3 threads. By default, this will run in all technologies. - -To run a specific test in all technologies: -``` -cd OpenRAM/compiler/tests -make 05_bitcell_array_test -``` -To run a specific technology: -``` -cd OpenRAM/compiler/tests -TECHS=scn4m_subm make 05_bitcell_array_test -``` - -To increase the verbosity of the test, add one (or more) -v options and -pass it as an argument to OpenRAM: -``` -ARGS="-v" make 05_bitcell_array_test -``` - -Unit test results are put in a directory: -``` -OpenRAM/compiler/tests/results// -``` -If the test fails, there will be a tmp directory with intermediate results. -If the test passes, this directory will be deleted to save space. -You can view the .out file to see what the output of a test is in either case. +Please see our [documentation][documentation] and let us know if anything needs +updating. # Get Involved diff --git a/docs/source/basic_setup.md b/docs/source/basic_setup.md new file mode 100644 index 00000000..74ed7b46 --- /dev/null +++ b/docs/source/basic_setup.md @@ -0,0 +1,76 @@ +### [Go Back](./index.md#directory) + +This page shows the basic setup for using OpenRAM. + +# Basic Setup + +## Dependencies + +Please see the Dockerfile for the required versions of tools. + +In general, the OpenRAM compiler has very few dependencies: ++ Docker ++ Make ++ Python 3.6 or higher ++ Various Python packages (pip install -r requirements.txt) ++ [Git] + +## Docker + +We have a [docker setup](./docker) to run OpenRAM. To use this, you should run: +``` +cd OpenRAM/docker +make build +``` +This must be run once and will take a while to build all the tools. + + +## Environment + +You must set two environment variables: ++ OPENRAM\_HOME should point to the compiler source directory. ++ OPENERAM\_TECH should point to one or more root technology directories (colon separated). + +You should also add OPENRAM\_HOME to your PYTHONPATH. + +For example add this to your .bashrc: + +``` + export OPENRAM_HOME="$HOME/OpenRAM/compiler" + export OPENRAM_TECH="$HOME/OpenRAM/technology" +``` + +You should also add OPENRAM\_HOME to your PYTHONPATH: +``` + export PYTHONPATH=$OPENRAM_HOME +``` + +Note that if you want symbols to resolve in your editor, you may also want to add the specific technology +directory that you use and any custom technology modules as well. For example: +``` + export PYTHONPATH="$OPENRAM_HOME:$OPENRAM_TECH/sky130:$OPENRAM_TECH/sky130/custom" +``` + +We include the tech files necessary for [SCMOS] SCN4M_SUBM, +[FreePDK45]. The [SCMOS] spice models, however, are +generic and should be replaced with foundry models. You may get the +entire [FreePDK45 PDK here][FreePDK45]. + + +### Sky130 Setup + +To install [Sky130], you must have the open_pdks files installed in $PDK_ROOT. +To install this automatically, you can run: + +``` +cd $HOME/OpenRAM +make pdk +``` + +Then you must also install the [Sky130] SRAM build space and the appropriate cell views +by running: + +``` +cd $HOME/OpenRAM +make install +``` diff --git a/docs/source/basic_usage.md b/docs/source/basic_usage.md index 0df0f49d..d2a81317 100644 --- a/docs/source/basic_usage.md +++ b/docs/source/basic_usage.md @@ -28,9 +28,54 @@ This page of the documentation explains the basic usage of OpenRAM. ## Command Line Usage -* Basic command line (with or without py suffix): - * `openram.py config` - * `openram.py config.py` + +Once you have defined the environment, you can run OpenRAM from the command line +using a single configuration file written in Python. + +For example, create a file called *myconfig.py* specifying the following +parameters for your memory: +``` +# Data word size +word_size = 2 +# Number of words in the memory +num_words = 16 + +# Technology to use in $OPENRAM_TECH +tech_name = "scn4m_subm" + +# You can use the technology nominal corner only +nominal_corner_only = True +# Or you can specify particular corners +# Process corners to characterize +# process_corners = ["SS", "TT", "FF"] +# Voltage corners to characterize +# supply_voltages = [ 3.0, 3.3, 3.5 ] +# Temperature corners to characterize +# temperatures = [ 0, 25 100] + +# Output directory for the results +output_path = "temp" +# Output file base name +output_name = "sram_{0}_{1}_{2}".format(word_size,num_words,tech_name) + +# Disable analytical models for full characterization (WARNING: slow!) +# analytical_delay = False + +``` + +You can then run OpenRAM by executing: +``` +python3 $OPENRAM_HOME/openram.py myconfig +``` +You can see all of the options for the configuration file in +$OPENRAM\_HOME/options.py + +To run designs in Docker, it is suggested to use, for example: +``` +cd OpenRAM/macros +make example_config_scn4m_subm +``` + * Common arguments: * `-t` specify technology (scn4m_subm or scmos or freepdk45) * `-v` increase verbosity of output @@ -128,4 +173,4 @@ The final results files are: ## Data Sheets ![Datasheet 1](../assets/images/basic_usage/datasheet_1.png) ![Datasheet 2](../assets/images/basic_usage/datasheet_2.png) -![Datasheet 3](../assets/images/basic_usage/datasheet_3.png) \ No newline at end of file +![Datasheet 3](../assets/images/basic_usage/datasheet_3.png) diff --git a/docs/source/debug.md b/docs/source/debug.md index c455a6ab..786976e3 100644 --- a/docs/source/debug.md +++ b/docs/source/debug.md @@ -41,6 +41,41 @@ OpenRAM has the set of thorough regression tests implemented with the Python uni ## Running Unit Tests + +Regression testing performs a number of tests for all modules in OpenRAM. +From the unit test directory ($OPENRAM\_HOME/tests), +use the following command to run all regression tests: + +``` +cd OpenRAM/compiler/tests +make -j 3 +``` +The -j can run with 3 threads. By default, this will run in all technologies. + +To run a specific test in all technologies: +``` +cd OpenRAM/compiler/tests +make 05_bitcell_array_test +``` +To run a specific technology: +``` +cd OpenRAM/compiler/tests +TECHS=scn4m_subm make 05_bitcell_array_test +``` + +To increase the verbosity of the test, add one (or more) -v options and +pass it as an argument to OpenRAM: +``` +ARGS="-v" make 05_bitcell_array_test +``` + +Unit test results are put in a directory: +``` +OpenRAM/compiler/tests/results// +``` +If the test fails, there will be a tmp directory with intermediate results. +If the test passes, this directory will be deleted to save space. +You can view the .out file to see what the output of a test is in either case. * Tests can be run in the `$OPENRAM_HOME/tests` directory * Command line arguments * `-v` for verbose @@ -52,7 +87,6 @@ OpenRAM has the set of thorough regression tests implemented with the Python uni * `regress.py` - ## Successful Unit Tests ```console user@host:/openram/compiler/tests$ ./regress.py @@ -138,4 +172,8 @@ FAILED (failures=1) * SPICE netlist for intermediate module results (`temp.sp`) * Extracted layout netlist for intermediate module results (`extracted.sp`) * Magic only: Run scripts for DRC (`run_drc.sh`) and LVS (`run_lvs.sh`) -* Calibre only: Runset file for DRC (`drc_runset`) and LVS (`lvs_runset`) \ No newline at end of file +* Calibre only: Runset file for DRC (`drc_runset`) and LVS (`lvs_runset`) + + + + diff --git a/docs/source/index.md b/docs/source/index.md index 6f854faf..167ed550 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,48 +5,29 @@ These pages provide the documentation of OpenRAM. You can use the links below to -## Directory +## Table of Contents +1. [OpenRAM Dependencies](#openram-dependencies) +1. [Supported Technologies](#supported-technologies) +1. [Bitcells](./bitcells.md#go-back) +1. [Architecture](./architecture.md#go-back) +1. [Implementation](#implementation) +1. [Technology and Tool Portability](#technology-and-tool-portability) +1. [Basic Usage](./basic_usage.md#go-back) +1. [Tutorials](./tutorials.md#go-back) +1. [Debugging and Unit Testing](./debug.md#go-back) +1. [Technology Setup](./technology_setup.md#go-back) +1. [Library Cells](./library_cells.md#go-back) +1. [Base Data Structures](./base_data_structures.md#go-back) +1. [Hierarchical Design Modules](./design_modules.md#go-back) +1. [Control Logic and Timing](./control_logic.md#go-back) +1. [Routing](./routing.md#go-back) +1. [Characterization](./characterization.md#go-back) +1. [Results](./results.md#go-back) +1. [FAQ](./FAQ.md#go-back) 1. [Contributors/Collaborators](#contributorscollaborators) -2. [OpenRAM Dependencies](#openram-dependencies) -3. [Supported Technologies](#supported-technologies) -4. [Bitcells](./bitcells.md#go-back) -5. [Architecture](./architecture.md#go-back) -6. [Implementation](#implementation) -7. [Technology and Tool Portability](#technology-and-tool-portability) -8. [Basic Usage](./basic_usage.md#go-back) -9. [Tutorials](./tutorials.md#go-back) -10. [Debugging and Unit Testing](./debug.md#go-back) -11. [Technology Setup](./technology_setup.md#go-back) -12. [Library Cells](./library_cells.md#go-back) -13. [Base Data Structures](./base_data_structures.md#go-back) -14. [Hierarchical Design Modules](./design_modules.md#go-back) -15. [Control Logic and Timing](./control_logic.md#go-back) -16. [Routing](./routing.md#go-back) -17. [Characterization](./characterization.md#go-back) -18. [Results](./results.md#go-back) -19. [FAQ](./FAQ.md#go-back) -## Contributors/Collaborators - - -* Prof. Matthew Guthaus (UCSC) -* Prof. James Stine & Dr. Samira Ataei (Oklahoma State University) -* UCSC students: - * Bin Wu - * Hunter Nichols - * Michael Grimes - * Jennifer Sowash - * Jesse Cirimelli-Low - -* Many other past students: - * Jeff Butera - * Tom Golubev - * Marcelo Sero - * Seokjoong Kim - - ## OpenRAM Dependencies @@ -108,3 +89,23 @@ Commercial tools (optional): * Uses a wrapper interface with DRC and LVS tools that allow flexibility * DRC and LVS can be performed at all levels of the design hierarchy to enhance bug tracking. * DRC and LVS can be disabled completely for improved run-time or if licenses are not available. + +## Contributors/Collaborators + + +* Prof. Matthew Guthaus (UCSC) +* Prof. James Stine & Dr. Samira Ataei (Oklahoma State University) +* UCSC students: + * Bin Wu + * Hunter Nichols + * Michael Grimes + * Jennifer Sowash + * Jesse Cirimelli-Low + +* Many other past students: + * Jeff Butera + * Tom Golubev + * Marcelo Sero + * Seokjoong Kim + +