Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update index.rst #335

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Update index.rst #335

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d29400
Update index.rst
marwaneltoukhy Nov 8, 2023
bcf4c51
Fix Typos
marwaneltoukhy Nov 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 51 additions & 168 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Starting your project
#. To start the project you first need to create a new repository based on the `caravel_user_project <https://github.com/efabless/caravel_user_project/>`_ template and make sure your repo is public and includes a README.

* Follow https://github.com/efabless/caravel_user_project/generate to create a new repository.
* Clone the reposity using the following command:
* Clone the repository using the following command:

.. code:: bash

Expand Down Expand Up @@ -100,15 +100,15 @@ Starting your project

- caravel_lite (a lite version of caravel)
- management core for simulation
- openlane to harden your design
- OpenLane to harden your design
- pdk


#. Now you can start hardening your design

* To start hardening you project you need
- RTL verilog model for your design for OpenLane to harden
- A subdirectory for each macro in your project under ``openlane/`` directory, each subdirectory should include openlane configuration files for the macro
- A subdirectory for each macro in your project under ``openlane/`` directory, each subdirectory should include OpenLane configuration files for the macro

.. code:: bash

Expand All @@ -119,35 +119,14 @@ Starting your project

#. Integrate modules into the user_project_wrapper

* Change the environment variables ``VERILOG_FILES_BLACKBOX``, ``EXTRA_LEFS`` and ``EXTRA_GDS_FILES`` in ``openlane/user_project_wrapper/config.tcl`` to point to your module
* Change the variables ``VERILOG_FILES_BLACKBOX``, ``EXTRA_LEFS`` and ``EXTRA_GDS_FILES`` in ``openlane/user_project_wrapper/config.json`` to point to your module
* Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v``
* Harden the user_project_wrapper including your module(s), using this command:

.. code:: bash

make user_project_wrapper

#. Run simulation on your design

* You need to include your rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project``

**NOTE:** You shouldn't include the files inside the verilog code

.. code:: bash

# you can then run RTL simulations using
make verify-<testbench-name>-rtl

# OR GL simulation using
make verify-<testbench-name>-gl

# OR for GL+SDF simulation using
# sdf annotated simulation is slow
make verify-<testbench-name>-gl-sdf

# for example
make verify-io_ports-rtl

#. Run cocotb simulation on your design

* rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project`` should be updated
Expand All @@ -170,7 +149,7 @@ Starting your project
* Add cocotb tests under ``verilog/dv/cocotb`` follow steps at `Adding_cocotb_test <https://caravel-sim-infrastructure.readthedocs.io/en/latest/usage.html#adding-a-test>`_
* Run cocotb tests using ``caravel_cocotb`` command steps at `Running_cocotb_tests <https://caravel-sim-infrastructure.readthedocs.io/en/latest/usage.html#running-a-test>`_

#. Run opensta on your design
#. Run OpenSTA on your design

* Extract spefs for ``user_project_wrapper`` and macros inside it:

Expand All @@ -184,22 +163,14 @@ Starting your project

make create-spef-mapping

* Run opensta:
* Run OpenSTA:

.. code:: bash

make caravel-sta

**NOTE:** To update timing scripts run ``make setup-timing-scripts``

#. Run standalone LVS

.. code:: bash

make lvs-<macro_name> # macro is the name of the macro you want to run LVS on

**NOTE:** You have to create a new config file for each macro under ``lvs/<macro_name>/lvs_config.json``

#. Run the precheck locally

.. code:: bash
Expand All @@ -210,33 +181,37 @@ Starting your project
#. You are done! now go to https://efabless.com/open_shuttle_program/ to submit your project!


Updating For New Release
========================

**NOTE: This is a temporary solution**


To update the makefile to get updated PDK and OpenLane versions, you can run this command from the project root

.. code:: bash

curl https://raw.githubusercontent.com/efabless/caravel_user_project/main/Makefile > Makefile

OR

To update ``caravel``, ``mgmt_core_wrapper``, ``precheck``, ``timing-scripts`` to the new release

.. code:: bash

MPW_TAG=<new_tag> make setup


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-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``.
Caravel and mgmt soc files are kept separate from the user project, when running ``make setup``
these files are cloned with a specific tag (shuttle tag). caravel-lite is cloned by default,
which is a lite version of caravel that only has the files needed for a successful user project.

-------------------
Verilog Integration
Expand Down Expand Up @@ -306,7 +281,7 @@ The following values are redefined for assigning to GPIOs.
- GPIO_MODE_USER_STD_ANALOG


MPW_Prececk includes a check to confirm each GPIO is assigned a valid value.
MPW_Precheck includes a check to confirm each GPIO is assigned a valid value.

-------------------
Layout Integration
Expand Down Expand Up @@ -338,40 +313,15 @@ Then, run the RTL simulation by

.. code:: bash

export PDK_ROOT=<pdk-installation-path>
make verify-<testbench-name>-rtl

# For example
make verify-io_ports-rtl
make cocotb-verify-<test_name>-rtl

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>
make verify-<testbench-name>-gl

# For example
make verify-io_ports-gl

To make sure that your design is timing clean, one way is running sdf annotated gate-level simulation
Run the sdf annotated gate-level simulation by:

.. code:: bash

export PDK_ROOT=<pdk-installation-path>
make verify-<testbench-name>-gl-sdf

# For example
make verify-io_ports-gl-sdf

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>`__.

make cocotb-verify-<test_name>-gl

User Project Wrapper Requirements
=================================
Expand Down Expand Up @@ -416,8 +366,6 @@ 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
Expand All @@ -444,13 +392,11 @@ openlane:
| |pic1| | |pic2| | |pic3| |
| | | |
+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
| ex: |link1| | | ex: |link2| |
| ex: |link1| | | |
+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+

.. |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%
Expand Down Expand Up @@ -485,7 +431,7 @@ To reproduce hardening this project, run the following:

.. code:: bash

# DO NOT cd into openlane
# From the project root

# Run openlane to harden user_proj_example
make user_proj_example
Expand All @@ -495,49 +441,32 @@ To reproduce hardening this project, run the following:

For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__.

Runing transistor level LVS
Crucial steps for integrating project inside ``user_project_wrapper``:

#. Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v``
#. Change the variables ``VERILOG_FILES_BLACKBOX``, ``EXTRA_LEFS``, ``EXTRA_LIBS``, ``EXTRA_SPEFS`` and ``EXTRA_GDS_FILES`` in ``openlane/user_project_wrapper/config.json`` to point to your module
#. Make sure to adjust the ``openlane/user_project_wrapper/config.json`` file as needed
#. **DON'T** adjust the pin placement or power ring, this will cause errors in precheck and ultimately in tapeout
#. Make sure you connect the power correctly, by adjusting ``FP_PDN_MACRO_HOOKS`` to your project's needs

Running transistor level LVS
============================

For the design to pass precheck, a custom lvs configuration file for your design is needed, config file can be found under `lvs/<design_name>/lvs_config.json`
For the design to pass precheck, a custom lvs configuration file for your design is needed, config file can be found under ``lvs/<design_name>/lvs_config.json``

The `lvs_config.json` files are a possibly hierarchical set of files to set parameters for device level LVS
The ``lvs_config.json`` files are a possibly hierarchical set of files to set parameters for device level LVS

Required variables:

- **TOP_SOURCE** : Top source cell name.
- **TOP_LAYOUT** : Top layout cell name.
- **LAYOUT_FILE** : Layout gds data file.
- **LVS_SPICE_FILES** : A list of spice files.
- **LVS_VERILOG_FILES** : A list of verilog files. Note: files with child modules should be listed before parent modules. Not needed for purely analog designs.

Files must be defined as a absolute path beginning with a shell variable such as `$PDK_ROOT` or `$UPRJ_ROOT`.

Optional variable lists:
Hierarchical config files:
- **INCLUDE_CONFIGS** : List of configuration files to read recursively.

Extraction related. `*` may be used as a wild card character.
- **EXTRACT_FLATGLOB** : List of cell names to flatten before extraction.
Cells without text tend to work better if flattened.
Note: it is necessary to flatten all sub cells of any cells listed.
- **EXTRACT_ABSTRACT** : List of cells to extract as abstract devices.
Normally, cells that do not contain any devices will be flattened during netlisting.
Using this variable can prevent unwanted flattening of empty cells.
This has no effect of cells that are flattened because of a small number of layers.
Internal connectivity is maintained (at least at the top level).

LVS related. `*` may be used as a wild card character.
- **LVS_FLATTEN** : List of cells to flatten before comparing,
Sometimes matching topologies with mismatched pins cause errors at a higher level.
Flattening these cells can yield a match.
- **LVS_NOFLATTEN** : List of cells not to be flattened in case of a mismatch.
Lower level errors can propagate to the top of the chip resulting in long run times.
Specify cells here to prevent flattening. May still cause higher level problems if there are pin mismatches.
- **LVS_IGNORE** : List of cells to ignore during LVS.
Cells ignored result in LVS ending with a warning.
Generally, should only be used when debugging and not on the final netlist.
Ignoring cells results in a non-zero return code.

**NOTE**: Missing files and undefined variables result in fatal errors.
Files must be defined as a absolute path beginning with a shell variable such as ``$PDK_ROOT`` or ``$UPRJ_ROOT``.

For more information on LVS please check `Precheck's backend check documentation <https://github.com/efabless/mpw_precheck/tree/main/checks/be_checks#readme>`__

Running MPW Precheck Locally
=================================
Expand All @@ -547,7 +476,7 @@ You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__
.. code:: bash

# By default, this install the precheck in your home directory
# To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
# To change the installation path, run "export PRECHECK_ROOT=<precheck installation path>"
make precheck

This will clone the precheck repo and pull the latest precheck docker image.
Expand Down Expand Up @@ -600,52 +529,6 @@ Then, you can run then run timing by the following...
A summary of timing results is provided at the end of the flow.


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.

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
=================================

Expand Down
Loading