added index.rst
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