Add files via upload
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/_static/counter_32.png b/docs/source/_static/counter_32.png
new file mode 100644
index 0000000..cbe7e06
--- /dev/null
+++ b/docs/source/_static/counter_32.png
Binary files differ
diff --git a/docs/source/_static/wrapper.png b/docs/source/_static/wrapper.png
new file mode 100644
index 0000000..f9d177b
--- /dev/null
+++ b/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..4bbbc5d
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,360 @@
+.. 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| |User CI| |Caravel Build|
+
+Table of contents
+=================
+
+- `Overview <#overview>`__
+- `Install Caravel <#install-caravel>`__
+- `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.
+
+Prerequisites
+=============
+
+- Docker
+
+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"
+
+ git clone https://github.com/efabless/caravel_user_project.git
+ cd caravel_user_project
+ 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
+===================
+
+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/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 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
+ 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.
+
+The symbolic links are automatically set when you run ``make install``.
+
+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 wishbone 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>
+
+Building the PDK
+================
+
+You have two options for building the pdk:
+
+- Build the pdk natively.
+
+Make sure you have `Magic VLSI Layout Tool <http://opencircuitdesign.com/magic/index.html>`__ installed on your machine before building the pdk.
+
+.. code:: bash
+
+ # set PDK_ROOT to the path you wish to use for the pdk
+ export PDK_ROOT=<pdk-installation-path>
+
+ # 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
+
+- Build the pdk using openlane's docker image which has magic installed.
+
+.. code:: bash
+
+ # set PDK_ROOT to the path you wish to use for the pdk
+ export PDK_ROOT=<pdk-installation-path>
+
+ # 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-nonnative
+
+Running Full Chip Simulation
+============================
+
+First, you will need to install the simulation environment, by
+
+.. code:: bash
+
+ make simenv
+
+This will pull a docker image with the needed tools installed.
+
+Then, run the RTL and GL simulation by
+
+.. code:: bash
+
+ export PDK_ROOT=<pdk-installation-path>
+ export CARAVEL_ROOT=$(pwd)/caravel
+ # specify simulation mode: RTL/GL
+ export SIM=RTL
+ # Run IO ports testbench, make verify-io_ports
+ make verify-<dv-pattern>
+
+The verilog test-benches are under this directory
+`verilog/dv <https://github.com/efabless/caravel_user_project/tree/main/verilog/dv>`__. For more information on setting up the
+simulation environment and the available testbenches for this sample
+project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__.
+
+Hardening the User Project Macro using Openlane
+===============================================
+
+You will need to install openlane by running the following
+
+.. code:: bash
+
+ export OPENLANE_ROOT=<openlane-installation-path>
+ export OPENLANE_TAG=<latest-openlane-tag>
+ make openlane
+
+For detailed 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 <https://github.com/efabless/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>
+
+.. raw:: html
+
+ </p>
+
+To reproduce hardening this project, run the following:
+
+.. code:: bash
+
+ # Run openlane to harden user_proj_example
+ make user_proj_example
+ # Run openlane to harden user_project_wrapper
+ make user_project_wrapper
+
+
+Running Open-MPW Precheck Locally
+=================================
+
+You can install the precheck by running
+
+.. code:: bash
+
+ # By default, this install the precheck in your home directory
+ # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
+ make precheck
+
+This will clone the precheck repo and pull the latest precheck docker image.
+
+
+Then, you can run the precheck by running
+Specify CARAVEL_ROOT before running any of the following,
+
+.. code:: bash
+
+ # export CARAVEL_ROOT=$(pwd)/caravel
+ export CARAVEL_ROOT=<path-to-caravel>
+ make run-precheck
+
+This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
+
+
+Other Miscellaneous Targets
+============================
+
+The makefile provides a number of useful that targets that can run LVS, DRC, and XOR checks on your hardened design outside of openlane's flow.
+
+Run ```make help`` to display available targets.
+
+Specify CARAVEL_ROOT before running any of the following,
+
+.. code:: bash
+
+ # export CARAVEL_ROOT=$(pwd)/caravel
+ export CARAVEL_ROOT=<path-to-caravel>
+
+Run lvs on spice,
+
+.. code:: bash
+
+ make lvs-<macro_name>
+
+Run lvs on the gds,
+
+.. code:: bash
+
+ make lvs-gds-<macro_name>
+
+Run lvs on the maglef,
+
+.. code:: bash
+
+ make lvs-maglef-<macro_name>
+
+Run drc using magic,
+
+.. code:: bash
+
+ make drc-<macro_name>
+
+Run antenna check using magic,
+
+.. code:: bash
+
+ make antenna-<macro_name>
+
+Run XOR check,
+
+.. code:: bash
+
+ make xor-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
+.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
+ :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
+.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
+ :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml
