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