Merge branch 'caravel_lite' of https://github.com/efabless/caravel_project_example into caravel_lite
diff --git a/.github/scripts/precheck/run-precheck-drc.sh b/.github/scripts/precheck/run-precheck-drc.sh index 51dc751..c9808db 100644 --- a/.github/scripts/precheck/run-precheck-drc.sh +++ b/.github/scripts/precheck/run-precheck-drc.sh
@@ -14,11 +14,12 @@ # limitations under the License. # SPDX-License-Identifier: Apache-2.0 export TARGET_PATH=$(pwd) +export CARAVEL_ROOT=$(pwd)/caravel-lite cd .. 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 -u $(id -u $USER):$(id -g $USER) efabless/open_mpw_precheck:latest bash -c "python3 open_mpw_prechecker.py --drc_only -p $PDK_ROOT -t $TARGET_PATH" +docker run -v $(pwd):/usr/local/bin -v $TARGET_PATH:$TARGET_PATH -v $CARAVEL_ROOT:$CARAVEL_ROOT -v $PDK_ROOT:$PDK_ROOT -u $(id -u $USER):$(id -g $USER) efabless/open_mpw_precheck:latest bash -c "python3 open_mpw_prechecker.py --drc_only -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
diff --git a/.github/scripts/precheck/run-precheck.sh b/.github/scripts/precheck/run-precheck.sh index 263634e..6633afd 100644 --- a/.github/scripts/precheck/run-precheck.sh +++ b/.github/scripts/precheck/run-precheck.sh
@@ -14,11 +14,12 @@ # limitations under the License. # SPDX-License-Identifier: Apache-2.0 export TARGET_PATH=$(pwd) +export CARAVEL_ROOT=$(pwd)/caravel-lite cd .. 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 -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 -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 -ms develop" output=$TARGET_PATH/checks/full_log.log gzipped_file=$TARGET_PATH/checks/full_log.log.gz
diff --git a/README.md b/README.md index 3f94439..4db9031 100644 --- a/README.md +++ b/README.md
@@ -70,7 +70,7 @@ Refer to [user_project_wrapper](verilog/rtl/user_project_wrapper.v) for more information. <p align=”center”> -<img src="doc/counter_32.png" width="50%" height="10%"> +<img src="docs/source/_static/counter_32.png" width="50%" height="10%"> </p> # Running Full Chip Simulation @@ -91,7 +91,7 @@ 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="doc/wrapper.png" width="30%" height="5%"> +<img src="docs/source/_static/wrapper.png" width="30%" height="5%"> </p> To reproduce hardening this project, run the following:
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c715218 --- /dev/null +++ b/docs/Makefile
@@ -0,0 +1,37 @@ + +# 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 +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +
diff --git a/docs/environment.yml b/docs/environment.yml new file mode 100644 index 0000000..2bddf94 --- /dev/null +++ b/docs/environment.yml
@@ -0,0 +1,23 @@ +# 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 + +name: caravel-docs +channels: +- defaults +dependencies: +- python>=3.8 +- pip: + - -r file:requirements.txt
diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..f5c5383 --- /dev/null +++ b/docs/requirements.txt
@@ -0,0 +1,6 @@ +git+https://github.com/SymbiFlow/sphinx_materialdesign_theme.git#egg=sphinx-symbiflow-theme + +docutils +sphinx +sphinx-autobuild +sphinxcontrib-wavedrom
diff --git a/docs/source/README.rst b/docs/source/README.rst new file mode 100644 index 0000000..44e8a31 --- /dev/null +++ b/docs/source/README.rst
@@ -0,0 +1,189 @@ +.. 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/doc/counter_32.png b/docs/source/_static/counter_32.png similarity index 100% rename from doc/counter_32.png rename to docs/source/_static/counter_32.png Binary files differ
diff --git a/doc/wrapper.png b/docs/source/_static/wrapper.png similarity index 100% rename from doc/wrapper.png rename to docs/source/_static/wrapper.png Binary files differ
diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..f960f13 --- /dev/null +++ b/docs/source/conf.py
@@ -0,0 +1,89 @@ +# 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 + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'CIIC Harness' +copyright = '2020, efabless' +author = 'efabless' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinxcontrib.wavedrom', + 'sphinx.ext.mathjax', + 'sphinx.ext.todo' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + 'build', + 'Thumbs.db', + # Files included in other rst files. + 'introduction.rst', +] + + +# -- Options for HTML output ------------------------------------------------- +""" +html_theme_options = { + 'header_links' : [ + ("Home", 'index', False, 'home'), + ("GitHub", "https://github.com/efabless/caravel", True, 'code'), + ], + 'hide_symbiflow_links': True, + 'license_url' : 'https://www.apache.org/licenses/LICENSE-2.0', +} +""" +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +todo_include_todos = False + +numfig = True
diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..44e8a31 --- /dev/null +++ b/docs/source/index.rst
@@ -0,0 +1,189 @@ +.. 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
