EFIC-175 Update documentation (#44)
* Update index.rst
* Update index.rst
* Update index.rst
* Update index.rst
* Add pics
* Update index.rst
* Update index.rst
* Add wrapper pic
* Update index.rst
diff --git a/docs/source/_static/empty.png b/docs/source/_static/empty.png
new file mode 100644
index 0000000..4b7ae67
--- /dev/null
+++ b/docs/source/_static/empty.png
Binary files differ
diff --git a/docs/source/_static/layout.png b/docs/source/_static/layout.png
new file mode 100644
index 0000000..71ffad0
--- /dev/null
+++ b/docs/source/_static/layout.png
Binary files differ
diff --git a/docs/source/_static/option1.png b/docs/source/_static/option1.png
new file mode 100644
index 0000000..a88350b
--- /dev/null
+++ b/docs/source/_static/option1.png
Binary files differ
diff --git a/docs/source/_static/option2.png b/docs/source/_static/option2.png
new file mode 100644
index 0000000..5c604d6
--- /dev/null
+++ b/docs/source/_static/option2.png
Binary files differ
diff --git a/docs/source/_static/option3.png b/docs/source/_static/option3.png
new file mode 100644
index 0000000..7e346b3
--- /dev/null
+++ b/docs/source/_static/option3.png
Binary files differ
diff --git a/docs/source/_static/pitch.png b/docs/source/_static/pitch.png
new file mode 100644
index 0000000..2efc7a9
--- /dev/null
+++ b/docs/source/_static/pitch.png
Binary files differ
diff --git a/docs/source/index.rst b/docs/source/index.rst
index fa3f806..bde1986 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -32,10 +32,12 @@
- `Repo Integration <#repo-integration>`__
- `Verilog Integration <#verilog-integration>`__
+ - `Layout Integration <#layout-integration>`__
- `Running Full Chip Simulation <#running-full-chip-simulation>`__
-- `Hardening the User Project Macro using
- Openlane <#hardening-the-user-project-macro-using-openlane>`__
+- `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>`__
@@ -101,7 +103,7 @@
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
+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:
@@ -154,6 +156,21 @@
</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
================
@@ -162,7 +179,7 @@
- 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`.
+The pdk build is tested with magic version ``8.3.209``.
.. code:: bash
@@ -199,7 +216,7 @@
This will pull a docker image with the needed tools installed.
-Then, run the RTL and GL simulation by
+Then, run the RTL simulation by
.. code:: bash
@@ -207,16 +224,69 @@
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>
+ # Run RTL simulation on IO ports testbench, make verify-io_ports
+ make verify-<testbench-name>
-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
+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>`__.
-Hardening the User Project Macro using Openlane
-===============================================
+
+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
@@ -232,16 +302,45 @@
For detailed instructions on the openlane and the pdk installation refer
to
-`README <https://github.com/efabless/openlane/blob/master/README.md>`__.
+`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:
-1. Hardening the user macro, then embedding it in the wrapper
-2. Flattening the user macro with the wrapper.
-3. Placing multiple macros in the wrapper along with standard cells on the top level.
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+| 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| |
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
-For more details on hardening the user project macro using openlane, refer to `README <https://github.com/efabless/caravel/blob/master/openlane/README.rst>`__.
+.. |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
@@ -250,13 +349,13 @@
.. raw:: html
<p align="center">
- <img src="./_static/wrapper.png" width="50%" height="50%">
+ <img src="./_static/wrapper.png" width="30%" height="30%">
</p>
.. raw:: html
</p>
-
+
To reproduce hardening this project, run the following:
.. code:: bash
@@ -267,10 +366,12 @@
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 precheck by running
+You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ by running
.. code:: bash
