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

Update debugging documentation

This commit is contained in:
Eren Dogan 2023-03-16 15:04:58 -07:00
parent 6eebef8c72
commit c166a50f21
1 changed files with 47 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
docs/source/debug.md
View File

@ -1,7 +1,8 @@
### [Go Back](./index.md#table-of-contents) ### [Go Back](./index.md#table-of-contents)
# Debugging and Unit Testing # Debugging and Unit Testing
This page of the documentation explains the debugging and unit testing of OpenRAM. This page of the documentation explains the debugging and unit testing of
OpenRAM.
@ -16,11 +17,14 @@ This page of the documentation explains the debugging and unit testing of OpenRA
## Unit Tests ## Unit Tests
OpenRAM has the set of thorough regression tests implemented with the Python unit test framework: OpenRAM has the set of thorough regression tests implemented with the Python
* Unit tests allow users to add features without worrying about breaking functionality. unit test framework:
* Unit tests allow users to add features without worrying about breaking
functionality.
* Unit tests guide users when porting to new technologies. * Unit tests guide users when porting to new technologies.
* Every sub-module has its own regression test. * Every sub-module has its own regression test.
* There are regression tests for memory functionality, library cell verification, timing verification, and technology verification. * There are regression tests for memory functionality, library cell
verification, timing verification, and technology verification.
@ -33,7 +37,8 @@ OpenRAM has the set of thorough regression tests implemented with the Python uni
* `05-19_*_test.py` checks DRC and LVS of module cells (moving upward in hierarchy with numbers) * `05-19_*_test.py` checks DRC and LVS of module cells (moving upward in hierarchy with numbers)
* `20_*_test.py` check DRC and LVS of full SRAM layouts with various configurations. * `20_*_test.py` check DRC and LVS of full SRAM layouts with various configurations.
* `21_*_test.py` checks timing of full SRAMs and compares (with tolerance) to precomputed result. * `21_*_test.py` checks timing of full SRAMs and compares (with tolerance) to precomputed result.
> **Note**: These tests may fail using different simulators due to the tolerance level. > **Note**: These tests may fail using different simulators due to the
> tolerance level.
* `22_*_test.py` checks functional simulation of full SRAMs with various configurations. * `22_*_test.py` checks functional simulation of full SRAMs with various configurations.
* `23-25_*_test.py` checks lib, lef, and verilog outputs using diff. * `23-25_*_test.py` checks lib, lef, and verilog outputs using diff.
* `30_openram_test.py` checks command-line interface and whether output files are created. * `30_openram_test.py` checks command-line interface and whether output files are created.
@ -41,16 +46,20 @@ OpenRAM has the set of thorough regression tests implemented with the Python uni
## Running Unit Tests ## Running Unit Tests
Regression testing performs a number of tests for all modules in OpenRAM. From
Regression testing performs a number of tests for all modules in OpenRAM. the unit test directory (`$OPENRAM_HOME/tests`), use the following command to run
From the unit test directory ($OPENRAM\_HOME/tests), all regression tests:
use the following command to run all regression tests:
``` ```
cd OpenRAM/compiler/tests cd OpenRAM/compiler/tests
make -j 3 make -j 3
``` ```
The -j can run with 3 threads. By default, this will run in all technologies. Note that if you have not run openram, the conda environment will not be installed. You can install it by running OpenRAM/install_conda.sh (see [Basic Setup](basic_setup.md#anaconda) for more details).
The `-j` can run with 3 threads. By default, this will run in all technologies.
> **Note**: If you have not run openram before running unit tests, the conda
> environment will not be installed. You can install it by running
> `OpenRAM/install_conda.sh` (see [Basic Setup](basic_setup.md#anaconda) for
> more details).
To run a specific test in all technologies: To run a specific test in all technologies:
``` ```
@ -63,8 +72,8 @@ cd OpenRAM/compiler/tests
TECHS=scn4m_subm make 05_bitcell_array_test TECHS=scn4m_subm make 05_bitcell_array_test
``` ```
To increase the verbosity of the test, add one (or more) -v options and To increase the verbosity of the test, add one (or more) `-v` options and pass
pass it as an argument to OpenRAM: it as an argument to OpenRAM:
``` ```
ARGS="-v" make 05_bitcell_array_test ARGS="-v" make 05_bitcell_array_test
``` ```
@ -73,95 +82,52 @@ Unit test results are put in a directory:
``` ```
OpenRAM/compiler/tests/results/<technology>/<test> OpenRAM/compiler/tests/results/<technology>/<test>
``` ```
If the test fails, there will be a tmp directory with intermediate results. If the test fails, there will be a `tmp` directory with intermediate results. If
If the test passes, this directory will be deleted to save space. the test passes, this directory will be deleted to save space. You can view the
You can view the .out file to see what the output of a test is in either case. `.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 To preserve results on successful tests (done automatically if test fails):
* `-v` for verbose ```
* `-t` freepdk45 for tech KEEP=1 make 05_bitcell_array_test
* `-d` to preserve /tmp results (done automatically if test fails) ```
* Individual tests
* `01_library_drc_test.py`
* All tests
* `regress.py`
## Successful Unit Tests ## Successful Unit Tests
```console ```console
user@host:/openram/compiler/tests$ ./regress.py user@host:/openram/compiler/tests$ make
______________________________________________________________________________ scn4m_subm/12_tri_gate_array_test ... PASS!
|==============================================================================| scn4m_subm/19_pmulti_bank_test ... PASS!
|========= Running Test for: =========| freepdk45/21_ngspice_delay_global_test ... PASS!
|========= scn4m_subm =========| scn4m_subm/23_lib_sram_linear_regression_test ... PASS!
|========= ./regress.py =========|
|========= /tmp/openram_mrg_13245_temp/ =========|
|==============================================================================|
runTest (00_code_format_check_test.code_format_test) ... ok
runTest (01_library_drc_test.library_drc_test) ... ok
runTest (02_library_lvs_test.library_lvs_test) ... ok
runTest (03_contact_test.contact_test) ... ok
runTest (03_path_test.path_test) ... ok
. .
. .
. .
``` ```
```console ```console
user@host:/openram/compiler/tests$ ./03_ptx_1finger_nmos_test.py user@host:/openram/compiler/tests$ make 01_library_test
______________________________________________________________________________ scn4m_subm/01_library_test ... PASS!
|==============================================================================| freepdk45/01_library_test ... PASS!
|========= Running Test for: =========|
|========= scn4m_subm =========|
|========= ./03_ptx_1finger_nmos_test.py =========|
|========= /tmp/openram_mrg_13750_temp/ =========|
|==============================================================================|
.
----------------------------------------------------------------------
Ran 1 test in 0.596s
OK
``` ```
## Debugging Unsuccessful Unit Tests (or sram\_compiler.py) ## Debugging Unsuccessful Unit Tests (or sram\_compiler.py)
* You will get an ERROR during unit test and see a stack trace * You will get a FAIL during unit test
* Examine the temporary output files in the temp directory (/tmp/mydir) * You can see the output and stack trace in
`$OPENRAM_HOME/tests/results/<tech>/<test>.out`
* Examine the temporary output files in the temp directory
(`$OPENRAM_HOME/tests/results/<tech>/<test>/`)
```console ```console
_____________________________________________________________________________ user@host:/openram/compiler/tests$ make 01_library_test
|==============================================================================| scn4m_subm/01_library_test ... FAIL!
|========= Running Test for: =========|
|========= scn4m_subm =========|
|========= ./04_pinv_10x_test.py =========|
|========= /tmp/mydir =========|
|==============================================================================|
ERROR: file magic.py: line 174: DRC Errors pinv_0 2
F
======================================================================
FAIL: runTest (__main__.pinv_test)
----------------------------------------------------------------------
Traceback (most recent call last):
File "./04_pinv_10x_test.py", line 22, in runTest
self.local_check(tx)
File "/Users/mrg/openram/compiler/tests/testutils.py", line 45, in local_check
self.fail("DRC failed: {}".format(a.name))
AssertionError: DRC failed: pinv_0
----------------------------------------------------------------------
Ran 1 test in 0.609s
FAILED (failures=1)
``` ```
### It didn't finish... where are my files? ### It didn't finish... where are my files?
* OpenRAM puts all temporary files in a temporary directory named: * OpenRAM puts all temporary files in a temporary directory named:
* `/tmp/openram_<user>_<pid>_temp` * `$OPENRAM_HOME/tests/results/<tech>/<test>/`
* This allows multiple processes/users to simultaneously run * This allows multiple unit tests to simultaneously run
* This allows /tmp to be mapped to a RAM disk for faster performance
* After a successful run, the directory and contents are deleted * After a successful run, the directory and contents are deleted
* To preserve the contents, you can run with the `-d` option for debugging * To preserve the contents, you can run with the `KEEP` option for debugging
* `OPENRAM_TMP` will override the temporary directory location for debug
* `export OPENRAM_TMP="/home/myname/debugdir"`
@ -176,4 +142,3 @@ FAILED (failures=1)