Merge branch 'main' of https://github.com/efabless/caravel_project_example into caravel_lite
diff --git a/.github/scripts/build/run-xor.sh b/.github/scripts/build/run-xor.sh
index ff92358..c224d5b 100644
--- a/.github/scripts/build/run-xor.sh
+++ b/.github/scripts/build/run-xor.sh
@@ -15,7 +15,7 @@
# SPDX-License-Identifier: Apache-2.0
export UPRJ_ROOT=$(pwd)
-export CARAVEL_ROOT=$(pwd)/caravel
+export CARAVEL_ROOT=$(pwd)/caravel-lite
cd ..
export PDK_ROOT=$(pwd)/pdks
export IMAGE_NAME=efabless/openlane:$OPENLANE_TAG
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
