default README
diff --git a/README.md b/README.md
index 3706438..17a85df 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,480 @@
[](https://opensource.org/licenses/Apache-2.0) [](https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml) [](https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml)
-| :exclamation: Important Note |
-|-----------------------------------------|
-
## Please fill in your project documentation in this README.md file
Refer to [README](docs/source/index.rst) for this sample project documentation.
+
+
+.. 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>`__
+ - `Layout Integration <#layout-integration>`__
+
+- `Running Full Chip Simulation <#running-full-chip-simulation>`__
+- `User Project Wrapper Requirements <#user-project-wrapper-requirements>`__
+- `Hardening the User Project using
+ Openlane <#hardening-the-user-project-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
+
+ # If unset, CARAVEL_ROOT will be set to $(pwd)/caravel
+ # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
+ export CARAVEL_ROOT=$(pwd)/caravel
+
+ # 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/main branch. 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 <https://github.com/efabless/caravel/blob/master/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 as the golden wrapper `template <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__. 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>
+
+
+Layout Integration
+-------------------
+
+The caravel layout is pre-designed with an empty golden wrapper in the user space. You only need to provide us with a valid ``user_project_wrapper`` GDS file. And, as part of the tapeout process, your hardened ``user_project_wrapper`` will be inserted into a vanilla caravel layout to get the final layout shipped for fabrication.
+
+.. raw:: html
+
+ <p align="center">
+ <img src="./_static/layout.png" width="80%" height="80%">
+ </p>
+
+To make sure that this integration process goes smoothly without having any DRC or LVS issues, your hardened ``user_project_wrapper`` must adhere to a number of requirements listed at `User Project Wrapper Requirements <#user-project-wrapper-requirements>`__ .
+
+
+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.
+The pdk build is tested with magic version ``8.3.209``.
+
+.. 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 simulation by
+
+.. code:: bash
+
+ export PDK_ROOT=<pdk-installation-path>
+ export CARAVEL_ROOT=$(pwd)/caravel
+ # specify simulation mode: RTL/GL
+ export SIM=RTL
+ # Run RTL simulation on IO ports testbench, make verify-io_ports
+ make verify-<testbench-name>
+
+Once you have the physical implementation done and you have the gate-level netlists ready, it is crucial to run full gate-level simulations to make sure that your design works as intended after running the physical implementation.
+
+Run the gate-level simulation by:
+
+.. code:: bash
+
+ export PDK_ROOT=<pdk-installation-path>
+ export CARAVEL_ROOT=$(pwd)/caravel
+ # specify simulation mode: RTL/GL
+ export SIM=GL
+ # Run RTL simulation on IO ports testbench, make verify-io_ports
+ make verify-<testbench-name>
+
+
+This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the
+`verilog/dv <https://github.com/efabless/caravel_user_project/tree/main/verilog/dv>`__ directory. 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>`__.
+
+
+User Project Wrapper Requirements
+=================================
+
+Your hardened ``user_project_wrapper`` must match the `golden user_project_wrapper <https://github.com/efabless/caravel/blob/master/gds/user_project_wrapper_empty.gds.gz>`__ in the following:
+
+- Area ``(2.920um x 3.520um)``
+- Top module name ``"user_project_wrapper"``
+- Pin Placement
+- Pin Sizes
+- Core Rings Width and Offset
+- PDN Vertical and Horizontal Straps Width
+
+
+.. raw:: html
+
+ <p align="center">
+ <img src="./_static/empty.png" width="40%" height="40%">
+ </p>
+
+
+These fixed configurations are specified `here <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/fixed_wrapper_cfgs.tcl>`__ .
+
+However, you are allowed to change the following if you need to:
+
+- PDN Vertical and Horizontal Pitch & Offset
+
+.. raw:: html
+
+ <p align="center">
+ <img src="./_static/pitch.png" width="30%" height="30%">
+ </p>
+
+To make sure that you adhere to these requirements, we run an exclusive-or (XOR) check between your hardened ``user_project_wrapper`` GDS and the golden wrapper GDS after processing both layouts to include only the boundary (pins and core rings). This check is done as part of the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ tool.
+
+
+Hardening the User Project using OpenLane
+==========================================
+
+OpenLane Installation
+---------------------
+
+You will need to install openlane by running the following
+
+.. code:: bash
+
+ export OPENLANE_ROOT=<openlane-installation-path>
+
+ # you can optionally specify the openlane tag to use
+ # by running: export OPENLANE_TAG=<openlane-tag>
+ # if you do not set the tag, it defaults to the last verfied tag tested for this project
+
+ make openlane
+
+For detailed instructions on the openlane and the pdk installation refer
+to
+`README <https://github.com/The-OpenROAD-Project/OpenLane#setting-up-openlane>`__.
+
+Hardening Options
+-----------------
+
+There are three options for hardening the user project macro using
+openlane:
+
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+| Option 1 | Option 2 | Option 3 |
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+| Hardening the user macro(s) first, then inserting it in the | Flattening the user macro(s) with the | Placing multiple macros in the wrapper |
+| user project wrapper with no standard cells on the top level | user_project_wrapper | along with standard cells on the top level |
++==============================================================+============================================+============================================+
+| |pic1| | |pic2| | |pic3| |
+| | | |
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+| ex: |link1| | | ex: |link2| |
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+
+.. |link1| replace:: `caravel_user_project <https://github.com/efabless/caravel_user_project>`__
+
+.. |link2| replace:: `caravel_ibex <https://github.com/efabless/caravel_ibex>`__
+
+
+.. |pic1| image:: ./_static/option1.png
+ :width: 48%
+
+.. |pic2| image:: ./_static/option2.png
+ :width: 140%
+
+.. |pic3| image:: ./_static/option3.png
+ :width: 72%
+
+For more details on hardening macros using openlane, refer to `README <https://github.com/The-OpenROAD-Project/OpenLane/blob/master/docs/source/hardening_macros.md>`__.
+
+
+Running OpenLane
+-----------------
+
+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 without having any standard cells on the top level.
+
+.. raw:: html
+
+ <p align="center">
+ <img src="./_static/wrapper.png" width="30%" height="30%">
+ </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
+
+
+For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__.
+
+Running MPW Precheck Locally
+=================================
+
+You can install the `mpw-precheck <https://github.com/efabless/mpw_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 the mag view,
+
+.. 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
+=================================
+
+- ✔️ The project repo adheres to the same directory structure in this
+ repo.
+- ✔️ The project repo contain info.yaml at the project root.
+- ✔️ Top level macro is named ``user_project_wrapper``.
+- ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
+- ✔️ The hardened Macros are LVS and DRC clean
+- ✔️ The project contains a gate-level netlist for ``user_project_wrapper`` at verilog/gl/user_project_wrapper.v
+- ✔️ 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>`__
+- ✔️ The hardened ``user_project_wrapper`` adheres to the fixed wrapper configuration specified at `fixed_wrapper_cfgs <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/fixed_wrapper_cfgs.tcl>`__
+- ✔️ XOR check passes with zero total difference.
+- ✔️ Openlane summary reports are retained under ./signoff/
+- ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__
+
+.. |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
