Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 1 | .. raw:: html |
| 2 | |
| 3 | <!--- |
| 4 | # SPDX-FileCopyrightText: 2020 Efabless Corporation |
| 5 | # |
| 6 | # Licensed under the Apache License, Version 2.0 (the "License"); |
| 7 | # you may not use this file except in compliance with the License. |
| 8 | # You may obtain a copy of the License at |
| 9 | # |
| 10 | # http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | # |
| 12 | # Unless required by applicable law or agreed to in writing, software |
| 13 | # distributed under the License is distributed on an "AS IS" BASIS, |
| 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 | # See the License for the specific language governing permissions and |
| 16 | # limitations under the License. |
| 17 | # |
| 18 | # SPDX-License-Identifier: Apache-2.0 |
| 19 | --> |
| 20 | |
Marwan Abbas | 3f39010 | 2022-02-21 11:59:43 +0200 | [diff] [blame] | 21 | Quick start for caravel_user_project |
| 22 | ==================================== |
Marwan Abbas | 54c22d5 | 2022-02-22 12:27:50 +0200 | [diff] [blame] | 23 | |
Marwan Abbas | 90262c4 | 2022-02-22 12:34:29 +0200 | [diff] [blame] | 24 | ------------ |
| 25 | Dependencies |
| 26 | ------------ |
| 27 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 28 | - Docker: `Linux <https://hub.docker.com/search?q=&type=edition&offering=community&operating_system=linux&utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Windows <https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Mac with Intel Chip <https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Mac with M1 Chip <https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ |
Marwan Abbas | 90262c4 | 2022-02-22 12:34:29 +0200 | [diff] [blame] | 29 | |
| 30 | =============================================================================================================================================================== |
| 31 | |
| 32 | --------------------- |
| 33 | Starting your project |
| 34 | --------------------- |
| 35 | |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 36 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 37 | #. To start the project you need to first create an empty Git project on Github and make sure your repo is public and includes a README |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 38 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 39 | #. Open your Terminal. Create an empty folder to use as your Caravel workspace, and navigate to it. |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 40 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 41 | .. code:: bash |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 42 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 43 | # Create a directory and call it anything you want |
| 44 | mkdir -p caravel_tutorial |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 45 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 46 | # navigate into the directory |
| 47 | cd caravel_tutorial |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 48 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 49 | #. Clone caravel_user_project and setup the git environment as follows |
| 50 | |
| 51 | .. code:: bash |
| 52 | |
| 53 | # Make sure that "caravel_example" matches the empty github repo name in step 1 |
| 54 | git clone -b mpw-5b https://github.com/efabless/caravel_user_project caravel_example |
| 55 | cd caravel_example |
| 56 | git remote rename origin upstream |
| 57 | |
| 58 | # You need to put your empty github repo URL from step 1 |
| 59 | git remote add origin <your github repo URL> |
| 60 | |
| 61 | # Create a new branch, you can name it anything |
| 62 | git checkout -b <my_branch> |
| 63 | git push -u origin <my_branch> |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 64 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 65 | #. Now that your git environment is setup, it's time to setup your local environment. |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 66 | |
Marwan Abbas | a70e700 | 2022-02-23 16:12:46 +0200 | [diff] [blame^] | 67 | * This command will setup your environment by installing the following |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 68 | - caravel_lite (a lite version of caravel) |
| 69 | - management core for simulation |
| 70 | - openlane to harden your design |
| 71 | - pdk |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 72 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 73 | .. code:: bash |
| 74 | |
| 75 | make setup |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 76 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 77 | #. Now you can start hardening your design |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 78 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 79 | * To start hardening you project you need |
| 80 | - RTL verilog model for your design for OpenLane to harden |
Marwan Abbas | a70e700 | 2022-02-23 16:12:46 +0200 | [diff] [blame^] | 81 | - A subdirectory for each macro in your project under ``openlane/`` directory, each subdirectory should include openlane configuration files for the macro |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 82 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 83 | .. code:: bash |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 84 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 85 | make <module_name> |
| 86 | .. |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 87 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 88 | For an example of hardening a project please refer to `user_project_example <https://github.com/efabless/caravel_user_project/blob/dv-documentation-update/docs/source/index.rst#running-openlane>`_ |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 89 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 90 | #. Integrate modules into the user_project_wrapper |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 91 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 92 | - 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 |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 93 | |
Marwan Abbas | a70e700 | 2022-02-23 16:12:46 +0200 | [diff] [blame^] | 94 | - Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v`` |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 95 | |
Marwan Abbas | a70e700 | 2022-02-23 16:12:46 +0200 | [diff] [blame^] | 96 | - Harden the user_project_wrapper including your module(s), using this command |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 97 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 98 | .. code:: bash |
Marwan Abbas | fdff858 | 2022-02-22 17:05:31 +0200 | [diff] [blame] | 99 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 100 | make user_project_wrapper |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 101 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 102 | #. Run simulation on your design |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 103 | |
Marwan Abbas | a70e700 | 2022-02-23 16:12:46 +0200 | [diff] [blame^] | 104 | * You need to include your rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project`` |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 105 | |
| 106 | **NOTE:** You shouldn't include the files inside the verilog code |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 107 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 108 | .. code:: bash |
| 109 | |
| 110 | make simenv |
| 111 | |
| 112 | # you can then run RTL simulations using |
| 113 | make verify-<testbench-name>-rtl |
| 114 | |
| 115 | # OR GL simulation using |
| 116 | make verify-<testbench-name>-gl |
| 117 | |
| 118 | # for example |
| 119 | make verify-io_ports-rtl |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 120 | |
Marwan Abbas | 7ccab9c | 2022-02-23 14:30:41 +0200 | [diff] [blame] | 121 | #. Run the precheck locally |
| 122 | |
| 123 | .. code:: bash |
| 124 | |
| 125 | make precheck |
| 126 | make run-precheck |
| 127 | |
| 128 | #. You are done! now go to www.efabless.com to submit your project! |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 129 | |
| 130 | |
| 131 | .. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg |
| 132 | :target: https://opensource.org/licenses/Apache-2.0 |
| 133 | .. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg |
| 134 | :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml |
| 135 | .. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg |
| 136 | :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml |