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
