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 | ## Dependencies |
| 24 | |
| 25 | - 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 Apple 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 | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 26 | |
| 27 | 1. 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 |
| 28 | |
| 29 | 2. Open your Terminal. Create an empty folder to use as your Caravel workspace, and navigate to it. |
| 30 | |
| 31 | .. code:: bash |
| 32 | |
| 33 | # Create a directory and call it anything you want |
| 34 | mkdir -p caravel_tutorial |
| 35 | |
| 36 | # navigate into the directory |
| 37 | cd caravel_tutorial |
| 38 | |
| 39 | 3. Clone caravel_user_project and setup the git environment as follows |
| 40 | |
| 41 | .. code:: bash |
| 42 | |
| 43 | # Make sure that ``caravel_example`` matches the empty github repo name in step 1 |
Marwan Abbas | ceb0445 | 2022-02-20 21:26:07 +0200 | [diff] [blame] | 44 | git clone -b mpw-5b https://github.com/efabless/caravel_user_project caravel_example |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 45 | cd caravel_example |
| 46 | git remote rename origin upstream |
| 47 | |
| 48 | # You need to put your empty github repo URL from step 1 |
| 49 | git remote add origin <your github repo URL> |
| 50 | |
| 51 | # Create a new branch, you can name it anything |
| 52 | git checkout -b <my_branch> |
| 53 | git push -u origin <my_branch> |
| 54 | |
Marwan Abbas | 54c22d5 | 2022-02-22 12:27:50 +0200 | [diff] [blame^] | 55 | 4. Now that your git environment is setup, it's time to setup your local environment. |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 56 | |
| 57 | .. code:: bash |
| 58 | |
| 59 | # to install caravel-lite into your caravel_user_project |
| 60 | # you can install full caravel (not recommended) use ``export CARAVEL_LITE=0`` |
| 61 | make install |
kareem | b104c94 | 2022-02-15 06:05:35 -0800 | [diff] [blame] | 62 | |
kareem | b104c94 | 2022-02-15 06:05:35 -0800 | [diff] [blame] | 63 | # To install the management core for simulation |
| 64 | make install_mcw |
| 65 | |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 66 | # Install openlane for hardening your project |
Marwan Abbas | b579e00 | 2022-02-17 10:13:24 +0200 | [diff] [blame] | 67 | # make sure to change <directory_name> with the directory you created in step 2 (In this case it's caravel_tutorial) |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 68 | # in this case it is caravel_tutorial |
| 69 | export OPENLANE_ROOT=~/<directory_name>/openlane # you need to export this whenever you start a new shell |
| 70 | make openlane |
| 71 | |
| 72 | # Build the pdk |
| 73 | # make sure to change <directory_name> with the directory you created in step 1 |
| 74 | # in this case it is caravel_tutorial |
Marwan Abbas | 75ba573 | 2022-02-11 16:50:50 +0200 | [diff] [blame] | 75 | |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 76 | export PDK_ROOT=~/<directory_name>/pdks # you need to export this whenever you start a new shell |
| 77 | make pdk |
| 78 | |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 79 | 5. Now you can start hardening your design, for example |
| 80 | |
| 81 | .. code:: bash |
| 82 | |
| 83 | make user_proj_example |
| 84 | make user_project_wrapper |
| 85 | |
| 86 | 6. To run simulation on your design |
| 87 | |
| 88 | .. code:: bash |
| 89 | |
| 90 | make simenv |
| 91 | # you can run RTL/GL simulations by using |
| 92 | export SIM=RTL |
| 93 | # OR |
| 94 | export SIM=GL |
| 95 | |
| 96 | # you can then run the simulations using |
| 97 | make verify-<testbench-name> |
| 98 | |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 99 | # for example |
| 100 | make verify-io_ports |
| 101 | |
| 102 | 7. To run the precheck locally |
| 103 | |
| 104 | .. code:: bash |
| 105 | |
| 106 | make precheck |
| 107 | make run-precheck |
| 108 | |
| 109 | 17. You are done! now go to www.efabless.com to submit your project! |
| 110 | |
| 111 | |
| 112 | .. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg |
| 113 | :target: https://opensource.org/licenses/Apache-2.0 |
| 114 | .. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg |
| 115 | :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml |
| 116 | .. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg |
| 117 | :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml |