Merge branch pull request #5 into main
diff --git a/.github/scripts/precheck/run-precheck.sh b/.github/scripts/precheck/run-precheck.sh index ee31f7c..b248a79 100644 --- a/.github/scripts/precheck/run-precheck.sh +++ b/.github/scripts/precheck/run-precheck.sh
@@ -19,7 +19,7 @@ export PDK_ROOT=$(pwd)/precheck_pdks cd $TARGET_PATH/open_mpw_precheck/ -docker run -v $(pwd):/usr/local/bin -v $TARGET_PATH:$TARGET_PATH -v $PDK_ROOT:$PDK_ROOT -v $CARAVEL_ROOT:$CARAVEL_ROOT -u $(id -u $USER):$(id -g $USER) efabless/open_mpw_precheck:latest bash -c "python3 open_mpw_prechecker.py --skip_drc -p $PDK_ROOT -t $TARGET_PATH -c $CARAVEL_ROOT -ms develop" +docker run -v $(pwd):/usr/local/bin -v $TARGET_PATH:$TARGET_PATH -v $PDK_ROOT:$PDK_ROOT -v $CARAVEL_ROOT:$CARAVEL_ROOT -u $(id -u $USER):$(id -g $USER) efabless/open_mpw_precheck:latest bash -c "python3 open_mpw_prechecker.py --skip_drc -p $PDK_ROOT -t $TARGET_PATH -c $CARAVEL_ROOT" output=$TARGET_PATH/checks/full_log.log gzipped_file=$TARGET_PATH/checks/full_log.log.gz @@ -33,4 +33,4 @@ cnt=$(grep -c "All Checks PASSED!" $output) if ! [[ $cnt ]]; then cnt=0; fi if [[ $cnt -eq 1 ]]; then exit 0; fi -exit 2 \ No newline at end of file +exit 2
diff --git a/.gitmodules b/.gitmodules index e69de29..c73b442 100644 --- a/.gitmodules +++ b/.gitmodules
@@ -0,0 +1,3 @@ +[submodule "caravel-lite"] + path = caravel + url = https://github.com/efabless/caravel-lite
diff --git a/Makefile b/Makefile index 6003c1c..6006565 100644 --- a/Makefile +++ b/Makefile
@@ -66,7 +66,7 @@ # Openlane Makefile Targets BLOCKS = $(shell cd openlane && find * -maxdepth 0 -type d) .PHONY: $(BLOCKS) -$(BLOCKS): +$(BLOCKS): %: cd openlane && $(MAKE) $* # Install caravel
diff --git a/README.md b/README.md index 6beb4f2..242bb9b 100644 --- a/README.md +++ b/README.md
@@ -9,4 +9,4 @@ --- -Refer to [CARAVEL_USER](CARAVEL_USER.md) for this sample project documentation. +Refer to [README](docs/source/README.md) for this sample project documentation.
diff --git a/caravel b/caravel new file mode 160000 index 0000000..11aa3dd --- /dev/null +++ b/caravel
@@ -0,0 +1 @@ +Subproject commit 11aa3dd76bedd31270dc4b00aea8d3ed20a7970c
diff --git a/CARAVEL_USER.md b/docs/source/README.md similarity index 89% rename from CARAVEL_USER.md rename to docs/source/README.md index 913b13d..c08b72d 100644 --- a/CARAVEL_USER.md +++ b/docs/source/README.md
@@ -89,7 +89,7 @@ Refer to [user_project_wrapper](verilog/rtl/user_project_wrapper.v) for more information. <p align=”center”> -<img src="docs/source/_static/counter_32.png" width="50%" height="10%"> +<img src="_static/counter_32.png" width="50%" height="10%"> </p> # Running Full Chip Simulation @@ -105,10 +105,13 @@ Then, you will need to build the pdk to obtain the verilog views. ```bash +# set PDK_ROOT to the path you wish to use for the pdk export PDK_ROOT=<pdk-installation-path> -# specify skywater-pdk and open-pdks commit used for this project -export SKYWATER_COMMIT=db2e06709dc3d876aa6b74a5f3893fa5f1bc2a6e -export OPEN_PDKS_COMMIT=b9ffc1fd1cfc26cbca85a61c287ac799721f6e6a + +# you can optionally specify skywater-pdk and open-pdks commit used +# by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT +# if you do not set them, they default to the last verfied commits tested for this project + make pdk ``` @@ -130,10 +133,13 @@ First, you will need to install the pdk by ```bash +# set PDK_ROOT to the path you wish to use for the pdk export PDK_ROOT=<pdk-installation-path> -# specify skywater-pdk and open-pdks commit used for this project -export SKYWATER_COMMIT=db2e06709dc3d876aa6b74a5f3893fa5f1bc2a6e -export OPEN_PDKS_COMMIT=b9ffc1fd1cfc26cbca85a61c287ac799721f6e6a + +# you can optionally specify skywater-pdk and open-pdks commit used +# by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT +# if you do not set them, they default to the last verfied commits tested for this project + make pdk ``` @@ -141,7 +147,7 @@ ```bash export OPENLANE_ROOT=<openlane-installation-path> -export OPENLANE_TAG=v0.12 +export OPENLANE_TAG=mpw-two-a make openlane ``` @@ -158,12 +164,13 @@ For this sample project, we went for the first option where the user macro is hardened first, then it is inserted in the user project wrapper. <p align=”center”> -<img src="docs/source/_static/wrapper.png" width="30%" height="5%"> +<img src="_static/wrapper.png" width="30%" height="5%"> </p> To reproduce hardening this project, run the following: ```bash +# export tag to v0.12 because currently mpw-two-a tag doesn't have a docker image. export OPENLANE_TAG=v0.12 # Run openlane to harden user_proj_example make user_proj_example
diff --git a/docs/source/README.rst b/docs/source/README.rst deleted file mode 100644 index 44e8a31..0000000 --- a/docs/source/README.rst +++ /dev/null
@@ -1,189 +0,0 @@ -.. raw:: html - - <!--- - # SPDX-FileCopyrightText: 2020 Efabless Corporation - # - # Licensed under the Apache License, Version 2.0 (the "License"); - # you may not use this file except in compliance with the License. - # You may obtain a copy of the License at - # - # http://www.apache.org/licenses/LICENSE-2.0 - # - # Unless required by applicable law or agreed to in writing, software - # distributed under the License is distributed on an "AS IS" BASIS, - # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - # See the License for the specific language governing permissions and - # limitations under the License. - # - # SPDX-License-Identifier: Apache-2.0 - --> - -Caravel User Project -==================== - -|License| |CI| - -Table of contents -================= - -- `Overview <#overview>`__ -- `Caravel Integration <#caravel-integration>`__ - - - `Repo Integration <#repo-integration>`__ - - `Verilog Integration <#verilog-integration>`__ - -- `Running Full Chip Simulation <#running-full-chip-simulation>`__ -- `Hardening the User Project Macro using - Openlane <#hardening-the-user-project-macro-using-openlane>`__ -- `Checklist for Open-MPW - Submission <#checklist-for-open-mpw-submission>`__ - -Overview -======== - -This repo contains a sample user project that utilizes the -`caravel <https://github.com/efabless/caravel.git>`__ chip user space. -The user project is a simple counter that showcases how to make use of -`caravel's <https://github.com/efabless/caravel.git>`__ user space -utilities like IO pads, logic analyzer probes, and wishbone port. The -repo also demonstrates the recommended structure for the open-mpw -shuttle projects. - -Caravel Integration -=================== - -Repo Integration ----------------- - -Caravel files are kept separate from the user project by having caravel -as submodule. The submodule commit should point to the latest of caravel -master. The following files should have a symbolic link to -`caravel's <https://github.com/efabless/caravel.git>`__ corresponding -files: - -- `Root Makefile <Makefile>`__: This is to make sure that you adhere to - the required implementation of the ``compress`` and ``uncompress`` - targets. Also, - `caravel's <https://github.com/efabless/caravel.git>`__ Makefile - provides useful targets like running ``lvs``, ``drc``, and ``xor`` - checks. Run ``make help`` to display the available targets. - -- `Openlane Makefile <openlane/Makefile>`__: This provides an easier - way for running openlane to harden your macros. Refer to [ Hardening - the User Project Macro]. Also, the makefile retains the openlane - summary reports under the signoff directory. - -- `Pin order <openlane/user_project_wrapper/pin_order.cfg>`__ file for - the user wrapper: The hardened user project wrapper macro must have - the same pin order specified in caravel's repo. Failing to adhere to - the same order will fail the gds integration of the macro with - caravel's back-end. - -To create the symbolic links run the following: - -.. code:: bash - - # In case caravel is sub-moduled under the project root, export CARAVEL_ROOT=caravel - export CARAVEL_ROOT=<caravel-path> - - ln -s $CARAVEL_ROOT/Makefile Makefile - ln -s $CARAVEL_ROOT/openlane/Makefile openlane/Makefile - ln -s $CARAVEL_ROOT/openlane/user_project_wrapper_empty/pin_order.cfg openlane/user_project_wrapper/pin_order.cfg - -Verilog Integration -------------------- - -You need to create a wrapper around your macro that adheres to the -template at -`user\_project\_wrapper <caravel/verilog/rtl/__user_project_wrapper.v>`__. -The wrapper top module must be named ``user_project_wrapper`` and must -have the same input and output ports. The wrapper gives access to the -user space utilities provided by caravel like IO ports, logic analyzer -probes, and wishbone bus connection to the management SoC. - -For this sample project, the user macro makes use of: - -- The IO ports for displaying the count register values on the IO pads. - -- The LA probes for supplying an optional reset and clock signals and - for setting an initial value for the count register. - -- The wishbeone port for reading/writing the count value through the - management SoC. - -Refer to `user\_project\_wrapper <verilog/rtl/user_project_wrapper.v>`__ -for more information. - -.. raw:: html - - <p align="center"> - <img src="./_static/counter_32.png" width="50%" height="50%"> - </p> - -.. raw:: html - - </p> - -Running Full Chip Simulation -============================ - -The verilog test-benches are under this `verilog/dv <verilog/dv>`__. For -more information on setting up the simulation environment and the -available testbenches for this sample project, refer to -`README <verilog/dv/README.md>`__. - -Hardening the User Project Macro using Openlane -=============================================== - -For instructions on how to install openlane and the pdk refer to -`README <https://github.com/efabless/openlane/blob/master/README.md>`__. - -There are two options for hardening the user project macro using -openlane: - -1. Hardening the user macro, then embedding it in the wrapper -2. Flattening the user macro with the wrapper. - -For more details on this, refer to this -`README <caravel/blob/master/openlane/README.rst>`__. - -For this sample project, we went for the first option where the user -macro is hardened first, then it is inserted in the user project -wrapper. - -.. raw:: html - - <p align="center"> - <img src="./_static/wrapper.png" width="50%" height="50%"> - </p> - -To reproduce hardening this project, run the following: - -.. code:: bash - - export OPENLANE_TAG=v0.12 - cd openlane - # Run openlane to harden user_proj_example - make user_proj_example - # Run openlane to harden user_project_wrapper - make user_project_wrapper - -Checklist for Open-MPW Submission -================================= - -- [x] The project repo adheres to the same directory structure in this - repo. -- [x] The project repo contain info.yaml at the project root. -- [x] Top level macro is named ``user_project_wrapper``. -- [x] Full Chip Simulation passes for RTL and GL (gate-level) -- [x] The hardened Macros are LVS and DRC clean -- [x] The hardened ``user_project_wrapper`` adheres to the same pin - order specified at - `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__ -- [x] XOR check passes with zero total difference. -- [x] Openlane summary reports are retained under ./signoff/ - -.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: https://opensource.org/licenses/Apache-2.0 -.. |CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_example_ci.yml/badge.svg - :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_example_ci.yml
diff --git a/docs/source/index.rst b/docs/source/index.rst index 44e8a31..83f8f0a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst
@@ -21,12 +21,13 @@ Caravel User Project ==================== -|License| |CI| +|License| |User CI| |Caravel Build| Table of contents ================= - `Overview <#overview>`__ +- `Install Caravel <#install-caravel>`__ - `Caravel Integration <#caravel-integration>`__ - `Repo Integration <#repo-integration>`__ @@ -49,6 +50,40 @@ repo also demonstrates the recommended structure for the open-mpw shuttle projects. +Install Caravel +=============== + +To setup caravel, run the following: + +.. code:: bash + + # By default, CARAVEL_ROOT is set to $(pwd)/caravel + # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>" + # Disable submodule installation if needed by, run "export SUBMODULE=0" + + make install + +To update the installed caravel to the latest, run: + +.. code:: bash + + make update_caravel + +To remove caravel, run + +.. code:: bash + + make uninstall + +By default +`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is +installed. To install the full version of caravel, run this prior to +calling make install. + +.. code:: bash + + export CARAVEL_LITE=0 + Caravel Integration =================== @@ -56,22 +91,17 @@ ---------------- Caravel files are kept separate from the user project by having caravel -as submodule. The submodule commit should point to the latest of caravel -master. The following files should have a symbolic link to -`caravel's <https://github.com/efabless/caravel.git>`__ corresponding -files: - -- `Root Makefile <Makefile>`__: This is to make sure that you adhere to - the required implementation of the ``compress`` and ``uncompress`` - targets. Also, - `caravel's <https://github.com/efabless/caravel.git>`__ Makefile - provides useful targets like running ``lvs``, ``drc``, and ``xor`` - checks. Run ``make help`` to display the available targets. +as submodule. The submodule commit should point to the latest of +caravel/caravel-lite master. The following files should have a symbolic +link to `caravel's <https://github.com/efabless/caravel.git>`__ +corresponding files: - `Openlane Makefile <openlane/Makefile>`__: This provides an easier - way for running openlane to harden your macros. Refer to [ Hardening - the User Project Macro]. Also, the makefile retains the openlane - summary reports under the signoff directory. + way for running openlane to harden your macros. Refer to `Hardening + the User Project Macro using + Openlane <#hardening-the-user-project-macro-using-openlane>`__. Also, + the makefile retains the openlane summary reports under the signoff + directory. - `Pin order <openlane/user_project_wrapper/pin_order.cfg>`__ file for the user wrapper: The hardened user project wrapper macro must have @@ -79,16 +109,7 @@ the same order will fail the gds integration of the macro with caravel's back-end. -To create the symbolic links run the following: - -.. code:: bash - - # In case caravel is sub-moduled under the project root, export CARAVEL_ROOT=caravel - export CARAVEL_ROOT=<caravel-path> - - ln -s $CARAVEL_ROOT/Makefile Makefile - ln -s $CARAVEL_ROOT/openlane/Makefile openlane/Makefile - ln -s $CARAVEL_ROOT/openlane/user_project_wrapper_empty/pin_order.cfg openlane/user_project_wrapper/pin_order.cfg +The symbolic links are automatically set when you run ``make install``. Verilog Integration ------------------- @@ -119,7 +140,7 @@ <p align="center"> <img src="./_static/counter_32.png" width="50%" height="50%"> </p> - + .. raw:: html </p> @@ -127,15 +148,69 @@ Running Full Chip Simulation ============================ -The verilog